Introduction to Permissions-Policy: Controlling Browser Capabilities
Modern web browsers provide access to powerful APIs—camera, microphone, geolocation, payment information, and more—that enhance user experience but also create security risks if misused. The Permissions-Policy header (formerly known as Feature-Policy) is a security header that allows website owners to explicitly declare which browser features and APIs can be used on their site. By restricting browser capabilities to only those your application actually needs, you substantially reduce your attack surface and protect users from malicious scripts attempting to exploit these powerful features.
Understanding the Evolution from Feature-Policy to Permissions-Policy
The Permissions-Policy header represents the modern evolution of what was previously called the Feature-Policy header. The naming change reflects a broader shift in how the web security community thinks about browser capabilities. Rather than thinking about "features," the industry now conceptualizes them as "permissions"—capabilities that require user authorization and should be actively managed by developers.
This semantic shift is important because it reflects a security-first mindset. Features are things you might casually use. Permissions are things that grant access to sensitive data or hardware. By renaming the header, the standards bodies reinforced that developers should treat these capabilities as security-critical rather than as features to enable casually.
How Permissions-Policy Works: The Allowlist Approach
Permissions-Policy operates on an allowlist principle: you explicitly declare which origins are allowed to use each browser capability. By default, many modern capabilities are restricted, though this behavior varies across browsers and has evolved as security practices have improved.
A Permissions-Policy header might look like:
Permissions-Policy: geolocation=(), camera=(self "https://trusted-partner.com"), microphone=*
This example indicates:
geolocation=()- Geolocation is disabled completely, even by the site itselfcamera=(self "https://trusted-partner.com")- Camera access allowed only for the current origin and one trusted partnermicrophone=*- Microphone allowed from any origin (not recommended, but technically valid)
The flexibility of Permissions-Policy allows precise control over each capability. Common directives include camera, microphone, geolocation, payment, usb, magnetometer, accelerometer, and dozens more as new browser capabilities are introduced.
Reducing Attack Surface Through Explicit Denial
The primary security benefit of Permissions-Policy is attack surface reduction through explicit denial. If a malicious script somehow executes on your website (through a compromised dependency, third-party ad network, or other injection vulnerability), Permissions-Policy prevents that script from accessing sensitive APIs even if the script tries to use them.
Consider a scenario where a third-party advertisement script is compromised and attempts to access a user's camera or microphone. Without Permissions-Policy, this attack could succeed, capturing video or audio without the user's knowledge. With Permissions-Policy restricting camera and microphone access, the browser simply denies the request, regardless of what the script attempts.
This is a defense-in-depth principle: you assume compromise might occur and layer your defenses so that even if one defense fails, others remain intact. Content Security Policy (CSP) might prevent the malicious script from executing certain operations, but Permissions-Policy provides an additional layer that prevents access to powerful capabilities at the browser level.
Common Permissions Worth Restricting
Certain permissions are particularly sensitive and should be restricted unless your application genuinely requires them:
Geolocation - Few websites actually need user location data. If your application doesn't provide location-based features, setting geolocation=() prevents any script from attempting location tracking. This is one of the most recommended restrictions.
Camera and Microphone - These hardware access permissions represent some of the most invasive capabilities. Even legitimate uses (video conferencing, voice calls) should restrict these to the same origin only. Third-party services that require camera/microphone access can be allowed explicitly, but only specific trusted origins.
Payment Request API - The payment API allows sites to request sensitive payment information. Unless your application actually processes payments, set payment=() to prevent any script from attempting payment requests.
USB and Serial - These APIs grant access to hardware directly connected to the user's device. Unless your application specifically works with USB or serial devices, restrict these completely.
Sensors - Accelerometer, gyroscope, and magnetometer access can reveal user device movement and orientation, potentially enabling surveillance. Restrict these unless your application genuinely needs them.
Third-Party Script Management
One of the most important use cases for Permissions-Policy involves third-party scripts: analytics providers, ad networks, social media embeds, and other external content. These third parties should only have access to the specific capabilities they need.
An analytics script doesn't need camera, microphone, or payment access. An ad network might request geolocation to serve location-based ads, but this should be an explicit choice the website owner makes. By using Permissions-Policy to restrict third-party scripts, you ensure they can't exceed their intended scope even if they behave maliciously or are compromised.
For example, if you include a third-party video embed from a trusted provider, you might use:
Permissions-Policy: camera=(self "https://video-provider.com"), microphone=(self "https://video-provider.com")
This allows the video provider to access camera and microphone only for their specific origin, not for any arbitrary third party.
Cross-Origin Embedding Protection
Permissions-Policy also controls what capabilities are available when your site is embedded in an iframe on another domain. This is crucial for preventing unauthorized access to sensitive capabilities through embedded content.
If your application provides a widget that other websites embed, you can use Permissions-Policy to restrict which capabilities the embedding site can trigger. For instance, if your widget is embedded as an iframe, the parent site cannot trigger camera access through the embedded frame unless you explicitly allow it.
This becomes particularly important if your embedded widget is placed on untrusted third-party sites. The Permissions-Policy header on your widget ensures that regardless of where it's embedded, the embedding site cannot exceed the permissions you've explicitly granted.
Browser Compatibility and Rollout Strategy
Permissions-Policy has widespread but not universal browser support. All major browsers (Chrome, Firefox, Safari, Edge) support it, but some legacy browsers may not recognize the header. The old Feature-Policy header name is still supported in some contexts for backward compatibility.
A practical rollout strategy involves sending both headers during a transition period:
Feature-Policy: geolocation=(), camera=()
Permissions-Policy: geolocation=(), camera=()
This ensures broader compatibility while supporting modern browsers with the newer header name. As browser support matures, you can deprecate the Feature-Policy header in favor of Permissions-Policy.
Interaction with Permissions and User Consent
It's important to understand the relationship between Permissions-Policy and browser permissions. When a user grants permission to access a capability (by clicking "Allow" when a site requests camera access), that permission is separate from Permissions-Policy.
Permissions-Policy acts at the capabilities level: it controls whether an API is available at all. User permissions act at the browser level: even if an API is available due to Permissions-Policy, the browser still prompts the user before granting access. Both layers work together to create comprehensive permission management.
A user could deny camera access through the browser's permission dialog, even if your Permissions-Policy allows it. Conversely, if your Permissions-Policy denies camera access, the user will never see a permission prompt because the browser knows the capability isn't available on that page.
Testing and Validation of Permissions-Policy
Testing Permissions-Policy involves verifying that restricted capabilities actually fail when scripts attempt to use them. Browser developer tools show whether permissions are granted or denied. You can test by attempting API calls that should be blocked and confirming they fail gracefully.
More sophisticated testing involves security scanning tools that analyze your Permissions-Policy configuration and provide recommendations. Some security headers analysis tools can review your Permissions-Policy and identify capabilities you might have forgotten to restrict.
Relationship to Content Security Policy
While Permissions-Policy controls which browser APIs are available, Content Security Policy (CSP) controls where scripts can be loaded from and what they can do. These headers work together:
- CSP prevents unsafe inline scripts and scripts from untrusted origins
- Permissions-Policy restricts which APIs those scripts can access even if they execute
For comprehensive security, implement both headers. CSP provides the first line of defense by preventing malicious scripts from executing in the first place. Permissions-Policy provides the second line of defense by restricting what those scripts can do if they somehow execute.
Best Practices for Permissions-Policy Implementation
Start with a restrictive baseline: deny all potentially sensitive capabilities by default, then explicitly allow only those your application needs. This "deny by default, allow by exception" approach is more secure than the inverse.
Document why you need each permission. If you have camera=(self) in your header, document that your application uses peer-to-peer video calls that require camera access. This documentation helps you audit whether permissions are still needed as your application evolves.
Review permissions regularly. As your application evolves, some capabilities you previously enabled might no longer be needed. Regular audits ensure you're not carrying unnecessary permissions from legacy features.
Restrict third-party scripts aggressively. Explicitly specify which origins third-party services are allowed to access capabilities from. Avoid overly permissive allowlists like * unless absolutely necessary.
Use specific origins for trusted partners. Rather than allowing a broad domain, use the most specific origin possible. If a service is hosted at https://service.example.com, use that specific origin rather than allowing all subdomains.
Monitor permission usage. Log attempts to access restricted capabilities and alert on unexpected patterns. This helps identify when your site or third-party scripts are attempting to use capabilities they shouldn't need.
Future of Browser Permissions
As new browser capabilities are introduced (eye tracking, neural interfaces, AR/VR features), Permissions-Policy will evolve to encompass these new capabilities. The header provides a framework for managing whatever powerful APIs the web platform introduces in the future.
The trend in web security is toward more granular permission controls and explicit feature restrictions. Permissions-Policy represents this evolution—moving from an open model where all capabilities were available by default to a closed model where capabilities are explicitly granted only when needed.
Conclusion: Permissions-Policy as Part of Defense-in-Depth
Permissions-Policy is a critical security header that provides explicit control over browser capabilities. By restricting access to cameras, microphones, geolocation, payment APIs, and other sensitive features, you reduce your attack surface and protect users even if malicious code manages to execute on your site.
Implementing Permissions-Policy as part of a comprehensive security strategy—alongside Content Security Policy, HTTPS, secure dependency management, and other best practices—creates a defense-in-depth architecture where no single vulnerability completely compromises security. The header's ability to provide browser-level restrictions on sensitive APIs makes it an essential component of modern web application security.
