Control browser features with Permissions Policy

Manage how your page and third-party iframes on your page have access to browser features.

Kevin K. Lee

Permissions Policy, formerly known as Feature Policy, allows the developer to control the browser features available to a page, its iframes, and subresources, by declaring a set of policies for the browser to enforce. These policies are applied to origins provided in a response header origin list. The origin list can contain same-origins and cross-origins, and it allows the developer to control first-party and third-party access to browser features.

The user has the final decision to allow access to more powerful features, and needs to provide explicit permission by accepting a prompt.

Permissions Policy allows the top-level site to define what it and its third parties intend to use, and removes the burden from the user of determining whether the feature access request is legitimate or not. For example, by using Permissions Policy to block the geolocation feature for all third parties, the developer can be certain that no third party will gain access to the user's geolocation.

Changes to Permissions Policy

Permissions Policy was previously known as Feature Policy. The key concepts remain the same, but there are some important changes along with the name.

Structured Fields usage

Structured Fields provide a set of common data structures to standardize parsing and serialization of HTTP header field values. Learn more about Structured Fields from Fastly's blog post, "Improving HTTP with structured header fields".

  geolocation 'self' https://example.com; camera 'none'

  geolocation=(self "https://example.com"), camera=()

Combine headers with the iframe allow attribute

With Feature Policy, you could add the feature to a cross-origin frame by either adding the origin to the header origin list or adding an allow attribute to the iframe tag. With Permissions Policy, if you add a cross-origin frame to the origin list, the iframe tag for that origin must include the allow attribute. If the response does not contain a Permissions Policy header, the origin list is considered to have the default value of *. Adding the allow attribute to the iframe allows access to the feature.

Therefore, we recommend developers explicitly set the Permissions Policy header in the response, so that cross-origin iframes which aren't listed in the origin list are blocked from accessing this feature, even if allow is present.

Feature Policy can still be used after Chrome 88, but it acts as an alias for Permissions Policy. Other than the syntax, there is no difference in logic. If both Permissions Policy and Feature Policy headers are used together, the Permissions-Policy header will have higher priority, and will overwrite the value provided by the Feature-Policy header.

How do I use Permissions Policy?

Quick overview

Before we dive deep, take a quick look at a common scenario where you are the owner of a website and you want to control how your site and third-party code use browser features.

• Your site is https://your-site.example.
• Your site embeds an iframe from same-origin (https://your-site.example).
• Your site embeds an iframe from https://trusted-site.example that you trust.
• Your site also displays ads served by https://ad.example.
• You want to allow geolocation only for your site and the trusted site, not for the ad.

In this case, use the following header:

Permissions-Policy: geolocation=(self "https://trusted-site.example")

And explicitly set the allow attribute to the iframe tag for the trusted site:

<iframe src="https://trusted-site.example" allow="geolocation">