Control Privacy Sandbox features with Permissions Policy

Learn how to allow or deny a Privacy Sandbox feature usage on the page.

Permissions Policy overview

Permissions Policy is a web platform mechanism that allows a page to control access to features on the page. Using Permissions Policy, a page can allow or deny a feature to the top-level page itself and embedded cross-origin iframes.

When responding to the browser's request, the page's response header can define the policies to be applied on the page. Also, the iframe tag defines the allow attribute where necessary to enable the feature in the iframe (if the parent also has permission). Permissions are delegated from parent to child, and the child of an iframe will receive the permissions of the parent frame.

Permissions Policy works in conjunction with the response header and the allow attribute on iframes. The feature is only allowed if it's allowed by both the response header and the allow attribute. When a Permissions Policy header is not provided, then every feature header policy defaults to *. When an iframe's allow attribute isn't defined, then the attribute defaults to the default allowlist value.

If the default allowlist is *, then the feature is available to the top-level page and all cross-origin iframes on the page by default. It is equivalent to <iframe src="some-url" allow="feature *"/> and the allow attribute isn't required to be defined on the iframe.

If the value is self, then the feature is only available to the top-level page (and same-origin iframes), and is not available to the cross-origin iframes without explicit delegation by the page. It is equivalent to <iframe src="some-url" allow="feature 'self'"/> where self is the embedder origin. Therefore, the allow tag must be defined to enable the feature in a cross-origin iframe.

To learn more about Permissions Policy, see the following content:

Developer overview on Controlling browser features with Permissions Policy - Chrome for Developers
Developer reference documentation for Permissions Policy
W3C-hosted working draft for Permissions Policy

Permissions Policy for Privacy Sandbox features

The following table lists the Privacy Sandbox APIs controlled by Permissions Policy:

API	Directive	Description	Default allowlist
Attribution Reporting (Guide / Spec)	`attribution-reporting`	Allows the usage of the Attribution Reporting API	`*`
Federated Credential Management (Guide / Spec)	`identity-credentials-get`	Allows obtaining a credential object	`self`
Private Aggregation (Guide /Spec)	`private-aggregation`	Allows reporting using Private Aggregation	`*`
Private State Tokens (Guide/Spec)	`private-state-token-issuance`	Allows requesting a token	`self`
Private State Tokens (Guide/Spec)	`private-state-token-redemption`	Allows redeeming a token and sending a redemption record	`self`
Protected Audience (Guide / Spec)	`join-ad-interest-group`	Allows adding user to an interest group for the site	`*` during testing `self` in the future
Protected Audience (Guide / Spec)	`run-ad-auction`	Allows running an ad auction	`*`
Shared Storage (Spec)	`shared-storage`	Allows reading and writing with Shared Storage	`*`
Shared Storage (Spec)	`shared-storage-select-url`	Allows the URL Selection operation to be executed	`*`
Storage Access (Guide / Spec)	`storage-access`	Allows access to the Storage Access API	`*`
`requestStorageAccessFor` (Guide / Spec)	`top-level-storage-access`	Allows access to the top-level access via `requestStorageAccessFor()` for sites grouped in a Related Website Set	`*`
Topics (Guide / Spec)	`browsing-topics`	Allows generating topics for the user, and reading the generated topics	`*`
User-Agent Client Hints (Guide / Spec)	See the guide for the full list of headers	Allows the specified client hint to be available to the requester	See the spec for the full list of default allowlist values

Unlike with third-party cookies where the page owner has no granular control over how the cookies are used by third-party iframes, a page can allow or deny Privacy Sandbox APIs from being used by the page itself and third-parties on the page by utilizing Permissions Policy. For example, a page owner, such as a publisher, can use Permissions Policy to allow specified third-parties to run an ad auction, or deny all third-parties from reading the user's topics.

Many Privacy Sandbox features use the default allowlist value of * which allows any cross-site iframes to use the feature unless restricted by Permissions Policy. The page owner can override the default policy and use their own policy, allowing only specified origins on the page to use the feature. Note that cookie's default behavior is to be allowed in all frames except sandboxed iframes also, but it is not covered by permissions policy and its usage cannot be controlled by the embedder. *.

Some Privacy Sandbox features use the default allowlist value of self which denies the cross-origin iframes from using the feature without explicit declaration. The page owner must use the allow attribute when creating cross-origin iframes to allow access to the feature. At a later time, the default allowlist value of some Privacy Sandbox APIs, such as the join-ad-interest-group directive for Protected Audience, will change to self. More APIs may switch the default allowlist to self in the future.