Permissions-Policy Header Explained
How to restrict which powerful browser features a page and its embedded content are allowed to use.
Core Concept
Permissions-Policy lets a site explicitly control which powerful browser features — camera, microphone, geolocation, and others — a page and any embedded iframes are allowed to access.
It's the successor to the earlier Feature-Policy header, with a refined syntax and broader browser support.
Common Controlled Features
The header can restrict access to a wide range of browser APIs.
- camera and microphone — media capture access
- geolocation — location data access
- fullscreen and autoplay — user experience controls
Granular Per-Origin Control
Permissions-Policy can grant or deny feature access differently for the top-level page versus specific embedded iframe origins.
Why Restricting Features Matters for Third-Party Content
Embedded third-party iframes inherit browser feature access unless explicitly restricted, creating unnecessary exposure.
- An embedded ad or widget requesting camera access without a legitimate need
- Third-party scripts silently accessing geolocation
- Unexpected fullscreen takeovers by embedded content
Setting a Restrictive Default
A conservative approach denies access to sensitive features by default, then selectively permits what's actually needed.
This 'deny by default, allow explicitly' pattern mirrors the general security principle of least privilege applied to browser capabilities.
Least Privilege for Browser APIs
Denying sensitive features globally and explicitly permitting only what a specific page genuinely needs is the safest default configuration pattern.
Testing and Verifying Policy Effectiveness
Confirming the policy behaves as intended requires checking both the header and actual runtime behavior.
- Verify the header is present and correctly scoped per feature
- Test that legitimately needed features still function correctly
- Confirm third-party embeds can't access unintended features
Real-World Implementation
Permissions-Policy adoption is growing as browser feature APIs continue to expand.
- Publishers restricting ad iframe access to sensitive device features
- Privacy-focused sites minimizing exposed browser capabilities
- Security audits increasingly checking for Permissions-Policy presence
As browsers expose more powerful capabilities to the web platform, explicitly restricting unnecessary access becomes an increasingly important hardening step.
Common Mistakes to Avoid
A few common mistakes limit Permissions-Policy's effectiveness.
- Leaving the policy unset, granting embedded content default access to sensitive features.
- Setting an overly broad allow policy without a clear need for the granted access.
- Failing to test that legitimately needed features still work after applying restrictions.
- Overlooking third-party iframe access when auditing feature permissions.
- Not verifying actual runtime behavior after deploying the policy, only its syntax.
- Overlooking newer browser feature APIs that should also be restricted by policy.
- Assuming Permissions-Policy behaves identically to the older Feature-Policy header.
- Failing to test third-party embeds after tightening the policy.
- Overlooking that some legacy browsers only partially support Permissions-Policy directives.
- Assuming iframe-level restrictions automatically cascade to nested iframes within it.
- Failing to test each restricted feature individually rather than the policy as a whole.
- Overlooking that some mobile browsers have less mature Permissions-Policy support than desktop.
- Overlooking that some browser vendors ship experimental features behind flags not yet covered by policy defaults.
Best Practices Checklist
These practices help build an effective, least-privilege Permissions-Policy.
- Deny sensitive features by default, then selectively permit only what's genuinely needed.
- Test both restricted and permitted features thoroughly after deploying the policy.
- Audit third-party iframe access specifically as part of the review.
- Verify actual runtime behavior, not just header syntax, after deployment.
- Review the policy periodically as new browser features and integrations are added.
- Review and update the policy as new browser feature APIs are introduced.
- Understand the syntax differences between Permissions-Policy and the older Feature-Policy header.
- Test all third-party embeds thoroughly after tightening any feature restriction.
- Account for partial legacy browser support when relying on Permissions-Policy protection.
- Verify whether nested iframe restrictions actually cascade as expected in your specific browsers.
- Test each restricted feature individually to confirm the policy behaves as intended.
- Test Permissions-Policy behavior specifically on mobile browsers, not just desktop.
- Track browser vendor experimental feature flags that may eventually need explicit Permissions-Policy coverage.
Frequently Asked Questions
Frequently asked questions about the Permissions-Policy header.
What does Permissions-Policy actually control?
Access to powerful browser features like camera, microphone, and geolocation — for both the top-level page and any embedded iframes.
Why does embedded third-party content need separate feature restrictions?
Without an explicit policy, embedded content inherits browser feature access unless the host page explicitly restricts it.
What's the safest default configuration approach?
Denying sensitive features globally and explicitly permitting only what a specific page genuinely needs follows the principle of least privilege.
Can Permissions-Policy grant different access to different iframe origins?
Yes — it supports granular, per-origin control, allowing different feature access for the top-level page versus specific embedded content.
How is Permissions-Policy related to the older Feature-Policy header?
Permissions-Policy is its successor, offering a refined syntax and broader browser support for the same underlying concept.
Do I need to update Permissions-Policy as browsers add new features?
Yes — new browser APIs are added over time, and a policy that doesn't account for them may leave unnecessary access open by default.
Is Permissions-Policy syntax identical to Feature-Policy?
No — it uses a refined syntax, so directly porting a Feature-Policy configuration usually requires some adjustment.
What's the risk of tightening Permissions-Policy without testing embeds?
Legitimate third-party functionality relying on a now-restricted feature could break unexpectedly if not tested before deployment.
Do all browsers fully support Permissions-Policy?
Support has grown but isn't universal across every legacy browser version, making it worth verifying for your specific audience.
Do restrictions cascade automatically to nested iframes?
Behavior can vary, so testing nested iframe scenarios specifically is worthwhile rather than assuming automatic cascading.
Is Permissions-Policy support consistent between mobile and desktop browsers?
Not entirely — mobile browser support can lag behind desktop, making dedicated mobile testing worthwhile.
Do experimental browser features need Permissions-Policy coverage too?
Eventually yes — as flagged features graduate to stable release, policy configuration should be updated to explicitly cover them.
Check Permissions-Policy Configuration
Run a security headers scan to see a domain's current Permissions-Policy setup.
Launch Tool →