Dev.to Security 🔐 Cybersecurity 👁 0 📖 11 min read

Permissions-Policy header for website owners: what it controls, how allowlists work, and where it falls short

The Permissions-Policy header is a response header your server sends with a page. It lets the site, rather than whatever code happens to run on it, decide which browser features may be used on that page and inside any em

The Permissions-Policy header is a response header your server sends with a page. It lets the site, rather than whatever code happens to run on it, decide which browser features may be used on that page and inside any embedded frames. MDN describes it as a mechanism to allow and deny the use of browser features in a document or within any iframe elements in the document. The broader guide frames the idea the same way: it gives web developers a way to explicitly declare what functionality can and cannot be used on a website.

In this guide

  1. What the Permissions-Policy header does and why a business site might use it
  2. How a policy is written: directives and allowlists
  3. Defaults: leaving a feature out does not block it
  4. What visitors and your code experience when a feature is blocked
  5. Embedded content: the header sets the ceiling, the iframe picks from it
  6. Seeing violations: reporting endpoints
  7. Limits: browser support and the old Feature-Policy name
  8. Putting it together for your own site

What the Permissions-Policy header does and why a business site might use it

For a website owner the practical value is control over drift. Sites grow: plugins are added, marketing tags are pasted in, and video or map embeds appear on landing pages. MDN says the policies you define restrict what APIs the site's code can access, and that this lets you enforce best practices even as the codebase evolves, as well as more safely compose third-party content. In plain terms, if your brochure site never needs the visitor's camera or location, you can say so once in a header, and that statement keeps applying no matter who edits the site later.

The reason this matters is stated directly by the guide: the web offers functionality and APIs that may have privacy or security risks if abused, and in those cases you may wish to strictly limit how that functionality is used. The examples MDN gives include restricting a site from using sensitive devices like the camera, microphone, or speakers, and allowing iframes to use the Fullscreen API.

It helps to place this header next to ones you may already know. MDN says Permissions Policy is similar to Content Security Policy but controls features instead of security behavior. More generally, OWASP's HTTP security headers cheat sheet notes that proper response headers can help prevent problems such as cross-site scripting, clickjacking and information disclosure, and calls headers a booster for web security with easy implementation.

How a policy is written: directives and allowlists

Each policy entry pairs a feature name, called a directive, with an allowlist that says who may use it. The guide's own example for switching off location access entirely is Permissions-Policy: geolocation=(), and its example for allowing your own site plus two named partners is geolocation=(self "https://a.example.com" "https://b.example.com").

The allowlist values are few, and knowing them is most of the skill. An empty pair of parentheses means the feature is disabled in top-level and nested browsing contexts, so neither your page nor any frame inside it can use it. The value self allows the feature in your document and in nested frames from the same origin only. A quoted origin allows that specific origin. The wildcard * allows the feature for your page and for every embedded frame regardless of origin, which is the loosest option and the one to be most cautious about.

Two rules trip people up. First, MDN states that * and () may only be used on their own, while self and src may be combined with one or more origins; you cannot write a list that mixes the wildcard with named sites. Second, where wildcards in origins are supported, a pattern such as https://*.example.com covers subdomains, but MDN notes that it does not match the bare https://example.com. If your main site and its subdomains both need a feature, list both.

You can control several features in one go. The guide says several features can be controlled at the same time by sending the header with a comma-separated list of policies, or by sending a separate header for each policy, and it shows the two forms as equivalent. That gives your developer or host flexibility in how the header is configured, without changing what it means.

Defaults: leaving a feature out does not block it

The most important thing for an owner to understand is what happens to features you do not mention. MDN states that Permissions-Policy directives have a default allowlist, which is either * or self, and that the specific default for each directive is given on its reference page. The reference page adds that this default applies when the directive is not explicitly listed in a policy.

The consequence is spelled out in the guide: for the top-level document, a default of self or * enables the feature, because the document's own origin always matches both. So a header that lists only geolocation=() still leaves the camera, fullscreen and every other unlisted feature available to your own page under its default. A Permissions-Policy header is therefore not a firewall that denies everything unnamed. It only restricts what you explicitly name.

The guide notes one exception: Chrome's non-standard unload directive defaults to (), so that feature is disabled unless a policy enables it. Outside that case, the safe mental model is that silence means allowed for your own page.

Defaults also reach into embedded frames. According to MDN, the default allowlist applies to an iframe whose allow attribute does not name the feature, whether or not the parent's header does: self grants the feature to a same-origin frame, * grants it regardless of origin, and () does not grant it. When you review an embed, check the default for each feature it might want, not just your header.

The practical lesson is to decide feature by feature. If a capability is genuinely unused on your site and has privacy weight, naming it with an empty allowlist is what actually turns it off.

What visitors and your code experience when a feature is blocked

Blocking a feature does not usually produce a dramatic error page. MDN lists the ways a disabled feature shows up: a "Permission denied" result for JavaScript APIs that need a user's grant, APIs that return false values or throw an error, or APIs that are not exposed at all, as though they do not exist.

The directive reference gives concrete cases. For camera, the Promise returned by getUserMedia() rejects with a NotAllowedError if the permission is not allowed. For geolocation, when the policy is disabled, getCurrentPosition() and watchPosition() call their callbacks with a PERMISSION_DENIED error code. For fullscreen, the Promise returned by Element.requestFullscreen() rejects with a TypeError.

There is also a user-facing benefit. The guide says that, generally, when a Permissions Policy blocks a powerful feature, the user won't even be asked for permission to use it, and the Permissions API query() method returns denied. For a business site that means a tag or embed that tries to request location or camera access generally cannot put a prompt in front of your customer.

The flip side is breakage you have to anticipate. As a hypothetical example, if your site had a store locator that relied on geolocation, a policy of geolocation=() would make it fail quietly in the ways listed above. The cause of a broken widget after a header change is not established by the symptom alone, but the specific errors described here are what a policy block looks like, which gives your developer something concrete to look for.

Embedded content: the header sets the ceiling, the iframe picks from it

Many business sites embed someone else's content, such as a map or a video player. Permissions Policy has two tools for this. The guide describes them as the Permissions-Policy HTTP header, which controls feature usage in the response and any embedded content within the page, and the iframe allow attribute, which controls feature usage only in specific frames.

The two work as a ceiling and a selection. MDN says the header's allowlist for a feature defines the superset of origins that are potentially allowed to access it, and an iframe's allow attribute grants the feature to the origins it names, provided they are present in that superset. An embed cannot be granted something your header has already ruled out.

From that, MDN draws its advice: because of this inheritance behavior, it is a good idea to specify the widest acceptable support for a feature in the HTTP header, and then specify the subset of support you need in each iframe. As an example, if only a video partner needs fullscreen, the header can permit that partner's origin, and the specific video frame can then be the only place it is granted.

One behaviour deserves attention when you rely on embeds. MDN flags that, by default, if an iframe navigates to another origin, the policy is not applied to the origin it navigates to; listing that destination origin in the allow attribute carries the policy over. If an embed redirects from one domain to another, ask your developer to account for both.

Seeing violations: reporting endpoints

A policy you cannot observe is hard to maintain. The reference page says violations of a policy can be reported using the Reporting API. Reports go either to a server endpoint named in a per-directive report-to parameter, or otherwise to the endpoint named "default".

There is a dependency here worth knowing before anyone sets it up. MDN states that the endpoint name and its associated URL must be specified in a separate Reporting-Endpoints HTTP response header. The report-to parameter alone only names an endpoint; the second header tells the browser where that name points. If it is omitted, reports go to the default reporting endpoint if one has been defined.

The reference page attaches reporting to an individual directive, as an optional per-directive parameter. That means you can watch the features you care most about, such as location or camera, without collecting reports for everything.

Why bother? Reports tell you when some piece of code on your pages attempted to use a feature your policy forbids. On a site with many third-party tags, that is useful evidence about which embed or script is reaching for capabilities you did not expect, and whether a recent header change is blocking something your site depends on. Route report contents to someone who will read them.

Limits: browser support and the old Feature-Policy name

Permissions-Policy is not a universal guarantee. Both MDN pages carry the same warning: the feature is not Baseline because it does not work in some of the most widely-used browsers, and it is marked experimental, with advice to check the browser compatibility table carefully before using it in production. For a website owner, that means the header reduces risk for visitors whose browsers honour it, while visitors on browsers that do not support it get no protection from it. It belongs alongside your other controls, not in place of them.

The name has history, too. MDN notes that Permissions Policy used to be called Feature Policy, and that both the name and the HTTP header syntax changed, so anyone who configured Feature Policy in the past should bear that in mind and check browser support. The iframe allow syntax stayed the same. If your server or security plugin still sends an old Feature-Policy header, it is worth asking your developer whether it has been replaced with the current form.

Browser support is uneven, so it is worth confirming what the live site actually sends. You can use a website vulnerability scanner for an outside-in look at the headers on a site you own, then verify the details in your own browser.

Putting it together for your own site

A useful way to approach this header is as an inventory exercise rather than a technical one. List what your pages actually do: whether anything needs the visitor's location, camera or microphone, whether any embed needs fullscreen, and which outside companies provide those embeds. That list, not a template copied from elsewhere, is what your policy should express.

Then think in three groups. Features nothing on the site uses are candidates for an empty allowlist, because leaving them unnamed keeps them available under their defaults. Features only your own pages use fit self. Features a specific partner needs fit a named origin in the header, granted again only on that partner's frame.

Finally, treat any change as something to verify with the people who run the site, since a too-strict entry can quietly disable a feature customers rely on, and a too-loose one gives away the control you wanted. Keep the policy written down so the next person who adds a tag or embed knows what the header is meant to allow.

When you are ready to review what the live site sends, you can check your website for vulnerabilities from the outside and compare that with the inventory you just wrote down.

Questions and answers

What does the Permissions-Policy header do for a business website?

It lets the site, rather than whatever code happens to run on it, decide which browser features may be used on that page and inside any embedded frames.

Does leaving a feature out of Permissions-Policy block it?

It only restricts what you explicitly name.

What do the Permissions-Policy allowlist values mean?

An empty pair of parentheses means the feature is disabled in top-level and nested browsing contexts, so neither your page nor any frame inside it can use it.

How does Permissions-Policy affect embedded iframes like maps or videos?

An embed cannot be granted something your header has already ruled out.

Do all browsers support Permissions-Policy?

Permissions-Policy is not a universal guarantee.

What happens when a blocked feature is requested?

the user won't even be asked for permission to use it

Make a short list of the browser features and embeds your pages really use, and review it with whoever manages your site's headers. If you want a second look at the security headers a site you own sends, you can run a free website security scan.

Sources

  1. MDN: Permissions-Policy header
  2. MDN: Permissions Policy guide
  3. OWASP HTTP Security Headers Cheat Sheet

The original version of this article is on the HackerMe Security blog.

📰 Read the original article on Dev.to Security

Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.