Permissions Policy Guide

Modern browsers expose many powerful capabilities to websites: cameras, microphones, geolocation, fullscreen mode, screen capture, sensors, autoplay and other browser features. These capabilities are useful, but a website does not necessarily need access to all of them.

Permissions Policy is a browser security mechanism that allows a website to control which origins can use selected browser features. The main way to configure it is the Permissions-Policy HTTP response header.

For example, a website can configure a policy that prevents camera and microphone access entirely:

Permissions-Policy: camera=(), microphone=()

Permissions Policy is particularly useful for reducing unnecessary browser capabilities, limiting third-party iframe access and making the security model of a website more explicit.

What Is Permissions Policy?

Permissions Policy is a browser mechanism that allows a document to control whether selected powerful features can be used by itself and by embedded content.

The policy is configured through HTTP response headers and, in some cases, iframe attributes. It works at the browser level: the browser evaluates the policy before allowing a controlled feature to be used.

Permissions-Policy: geolocation=(), camera=(), microphone=()

The exact features that can be controlled depend on the Permissions Policy specification and browser support. Developers should therefore verify the current feature and browser compatibility before relying on a particular directive.

Why Does Permissions Policy Exist?

Websites increasingly embed content from third parties. A page may include analytics, advertising, video players, payment widgets, maps, social media components or other external applications.

Some embedded content can request access to powerful browser capabilities. Permissions Policy provides a way for the top-level site to define which features are available and where they can be used.

This follows the principle of least privilege: if an application does not need camera access, there is little reason to make camera functionality available to the page or its embedded content.

Permissions Policy vs Browser Permissions

Permissions Policy and browser permission prompts are related but are not the same thing.

A Permissions Policy can prevent a feature from being available in the first place. In that situation, a browser permission prompt does not provide a way for the page to bypass the policy.

The Permissions-Policy Header

The main HTTP mechanism is the Permissions-Policy response header.

Permissions-Policy: camera=(), microphone=()

The header contains one or more feature policies. Each policy specifies a controlled feature and an allowlist describing which origins can use it.

Permissions Policy Syntax

A basic policy has the form of a feature followed by an allowlist.

Permissions-Policy: feature=(allowlist)

Multiple policies can be separated by commas.

Permissions-Policy: geolocation=(), camera=(), microphone=()

The exact syntax of individual allowlist values depends on the policy. Common values include (), *, self and explicitly listed origins.

The Empty Allowlist ()

An empty allowlist disables a feature for the document and its embedded content under the policy.

Permissions-Policy: camera=(), microphone=()

This is useful when an application has no legitimate reason to use the corresponding browser capabilities.

The self Allowlist

The self keyword allows the feature for the current origin, subject to the feature's rules and the resulting policy.

Permissions-Policy: geolocation=(self)

This can be appropriate when a site uses a browser feature itself but does not want to make that feature available to arbitrary embedded origins.

The Wildcard Allowlist

The wildcard can be used when a feature should be allowed broadly under the applicable Permissions Policy rules.

Permissions-Policy: geolocation=*

Allowing a Specific Origin

A policy can explicitly identify an origin that should be permitted to use a feature.

Permissions-Policy: geolocation=(self "https://maps.example.com")

This type of configuration is useful when the top-level application uses a feature itself and also needs to delegate it to a specific embedded service.

Common Permissions Policy Features

Permissions Policy supports a range of controlled features. The exact set and browser support can change as web platform capabilities evolve.

Not every browser supports every feature identically. A production policy should therefore be based on the features the application actually uses and tested against the browsers that matter to its users.

Disabling Camera and Microphone

A website that does not use video or audio input can explicitly disable both capabilities.

Permissions-Policy: camera=(), microphone=()

This can also prevent embedded content from using these capabilities when the top-level policy does not delegate them.

Disabling Geolocation

If an application does not need location information, it can disable geolocation:

Permissions-Policy: geolocation=()

This is useful for applications that have no location-based functionality and do not want embedded content to request it through the page.

Allowing Geolocation for the Site

If the application itself needs geolocation, an explicit self policy can be used.

Permissions-Policy: geolocation=(self)

This expresses that the site's own origin may use the feature while avoiding a broad policy for other origins.

Permissions Policy and Iframes

One of the most important use cases for Permissions Policy is controlling embedded iframes. A top-level page can restrict which features are available to embedded documents.

<iframe
  src="https://video.example.com"
  allow="fullscreen"
  title="Video player"
></iframe>

The iframe allow attribute is used to delegate selected capabilities to embedded content. The final permission is affected by both the top-level Permissions Policy and the iframe's delegation.

The iframe allow Attribute

The allow attribute provides a way to specify which controlled features an iframe may use.

<iframe
  src="https://video.example.com"
  allow="camera; microphone"
  title="Video call"
></iframe>

An iframe's allow attribute does not automatically override the top-level Permissions Policy. The parent document still needs to permit the feature and delegation must satisfy the applicable policy.

Permissions Policy and Third-Party Content

Third-party embeds are one of the strongest reasons to understand Permissions Policy. A page may contain content from origins that the site operator does not fully control.

For example, a video conference provider may legitimately need microphone and camera access, while an unrelated embedded widget should not need either capability.

A restrictive top-level policy can establish a default boundary, after which specific features can be delegated to trusted embedded applications when necessary.

Permissions Policy and Least Privilege

Least privilege means giving an application only the capabilities it needs. Permissions Policy applies this principle to browser features.

• Disable camera access if the application does not use a camera.
• Disable microphone access if audio input is unnecessary.
• Disable geolocation if the application does not need location data.
• Restrict fullscreen to trusted embedded applications when possible.
• Delegate powerful features to specific iframe origins instead of broadly allowing them.
• Review third-party embeds when their required browser capabilities change.

Permissions Policy vs Content Security Policy

Permissions Policy and Content Security Policy are both browser security mechanisms, but they control different things.

These mechanisms complement one another. A CSP does not replace Permissions Policy, and Permissions Policy does not replace CSP.

Permissions Policy vs CORS

CORS controls access to cross-origin HTTP responses from browser JavaScript. Permissions Policy controls access to selected browser capabilities.

For example, an API request to another origin may require CORS, while camera access in an embedded application may require appropriate Permissions Policy configuration. These are separate browser security decisions.

Permissions Policy and Browser Permissions

A user permission prompt does not necessarily mean that the application is allowed to request the feature. Permissions Policy can establish an earlier restriction.

For example, if camera access is disabled by the document's Permissions Policy, an embedded application cannot simply display a browser prompt and bypass that restriction.

Permissions Policy and Secure Contexts

Many powerful browser capabilities have additional requirements, including secure contexts. HTTPS is therefore often a prerequisite for APIs involving sensitive device capabilities.

Permissions Policy does not remove those requirements. Instead, it adds another layer that can further restrict whether a feature is available.

Permissions Policy and User Consent

Permissions Policy should not be confused with user consent. Allowing a feature through the policy does not automatically grant the website access to the user's camera, microphone or location.

The browser can still apply permission prompts and other security rules. Permissions Policy determines whether the feature is available to the document in the first place.

A Practical Security Policy

A general-purpose site that does not use camera, microphone or geolocation can explicitly disable those capabilities.

Permissions-Policy: camera=(), microphone=(), geolocation=()

The exact policy should be based on the application's requirements. Adding directives for features that the site does not use can make the intended security boundary clearer, but the configuration should remain maintainable.

Delegating a Feature to an Embedded Service

Suppose a website embeds a trusted video conference application that needs camera and microphone access. The top-level policy can allow those features for the appropriate origin, while the iframe delegates them to the embedded document.

Permissions-Policy: camera=(self "https://meet.example.com"), microphone=(self "https://meet.example.com")

<iframe
  src="https://meet.example.com/room"
  allow="camera; microphone"
  title="Video conference"
></iframe>

The actual syntax and browser behavior should be tested with the target browser versions because feature support and policy processing can evolve.

Permissions Policy and Subframes

Permissions Policy is especially important in documents containing nested frames. The availability of a feature can be constrained as the document is embedded, and a child frame cannot simply grant itself a capability that the parent policy has prohibited.

This creates a useful security boundary for pages that integrate multiple independent applications or services.

Permissions Policy and Third-Party Scripts

A third-party script executing in the same document generally runs under the document's origin and security context. This differs from a third-party iframe, which has its own document origin.

Permissions Policy is therefore particularly valuable for controlling embedded documents. It should not be treated as a substitute for controlling which third-party JavaScript is allowed to execute on the page.

Permissions Policy and Ads

Advertising systems can involve third-party frames and scripts. A site can use Permissions Policy to limit access to selected powerful browser features where those capabilities are not required.

The policy should be based on the actual functionality required by the advertising integration. Blocking unrelated capabilities does not necessarily prevent advertisements from being displayed.

Common Permissions Policy Mistakes

Using a Wildcard Everywhere

A policy such as:

Permissions-Policy: camera=*, microphone=*, geolocation=*

is broader than necessary for most applications. If only one trusted origin needs a capability, an explicit policy can communicate that requirement more clearly.

Assuming an Empty Policy Solves Every Security Problem

Disabling camera, microphone and geolocation does not protect against unrelated browser or application security issues. Permissions Policy is one layer of defense and should be combined with appropriate authentication, authorization, CSP, secure transport and dependency controls.

Forgetting About Iframe Delegation

Adding a feature to the top-level Permissions-Policy header may not be enough for an embedded application. The iframe's allow attribute and the embedded origin must also satisfy the applicable policy.

Assuming Browser Permission Prompts Override Policy

A browser permission prompt does not override a document-level Permissions Policy restriction. If the feature is not available to the document, user consent cannot simply bypass that policy.

Copying an Old Header Configuration

Permissions Policy evolved from the older Feature-Policy mechanism. Old examples may use syntax or feature names that no longer represent current browser behavior. Always verify the current syntax and supported directives for the browsers being targeted.

Feature-Policy vs Permissions-Policy

Permissions Policy is the modern mechanism that replaced the older Feature Policy terminology and implementation. Older documentation may therefore refer to Feature-Policy.

When working on a current application, use current browser and specification documentation rather than copying an old Feature-Policy configuration without checking whether the syntax and features are still supported.

How to Debug Permissions Policy

Browser developer tools can provide useful information when a feature is blocked by Permissions Policy. The exact diagnostic messages depend on the browser and feature.

• Open the browser developer tools.
• Check the Console for Permissions Policy warnings or errors.
• Inspect the document's response headers.
• Find the Permissions-Policy header.
• Check the feature that is being blocked.
• If an iframe is involved, inspect its allow attribute.
• Verify the iframe's origin against the policy.
• Check whether the feature requires a secure context.
• Check whether the browser supports the feature and policy directive.
• Test the final deployed response rather than only local configuration.

Testing the HTTP Header

The first step is to verify that the server actually returns the intended header.

HTTP/1.1 200 OK
Permissions-Policy: camera=(), microphone=(), geolocation=()

If a reverse proxy or CDN is involved, inspect the response received by the browser because the final header may differ from the application configuration.

Testing an Embedded Feature

For iframe-based applications, test both sides of the policy: the top-level HTTP header and the iframe allow attribute.

<iframe
  src="https://trusted.example.com"
  allow="camera; microphone"
  title="Trusted application"
></iframe>

If the feature remains unavailable, check whether the top-level policy permits the embedded origin and whether the browser supports the relevant feature.

Permissions Policy Behind a CDN or Reverse Proxy

Security headers can be added by several infrastructure layers. A CDN, reverse proxy, web server or application framework may all be capable of modifying response headers.

This can lead to situations where the local application configuration looks correct but the deployed website returns a different policy. Always inspect the final HTTP response when troubleshooting.

Permissions Policy in Nginx

Nginx can add a Permissions-Policy response header with add_header.

add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;

The exact placement depends on the Nginx configuration. If another infrastructure layer also manages security headers, verify which layer is responsible for the final response.

Permissions Policy in Apache

Apache can set the response header through mod_headers.

Header always set Permissions-Policy "camera=(), microphone=(), geolocation=()"

After changing the configuration, inspect the response headers from the deployed server rather than assuming that the configuration file alone proves that the header is active.

Permissions Policy in Next.js

A Next.js application can configure security headers through its response configuration or through the infrastructure serving the application.

const nextConfig = {
  async headers() {
    return [
      {
        source: "/(.*)",
        headers: [
          {
            key: "Permissions-Policy",
            value: "camera=(), microphone=(), geolocation=()"
          }
        ]
      }
    ];
  }
};

export default nextConfig;

The exact implementation can vary with the Next.js version and hosting environment. The important step is to verify the resulting HTTP response.

Permissions Policy and Security Header Sets

Permissions Policy works best as one component of a broader security-header configuration.

These headers should not be copied as a generic checklist without considering application requirements. Each one controls a different browser behavior.

When Should You Use Permissions Policy?

Permissions Policy is particularly useful when an application has a clear understanding of which powerful browser features it needs.

• Websites that do not need camera or microphone access.
• Applications that do not require geolocation.
• Pages that embed third-party iframes.
• Video or conferencing applications that need controlled media access.
• Applications that want explicit browser capability restrictions.
• Sites with a security-header management process.

When Permissions Policy Is Not Enough

Permissions Policy is not a replacement for application security. It does not authenticate users, authorize API requests, validate application input or protect secrets.

A secure application may need multiple layers, including authentication, authorization, CSRF protection where appropriate, Content Security Policy, secure cookies, HTTPS, dependency management and server-side validation.

A Practical Permissions Policy Checklist

• Identify which controlled browser features the application actually uses.
• Disable unnecessary powerful features where appropriate.
• Prefer explicit origins over broad wildcards when delegation is required.
• Review every third-party iframe that needs a controlled capability.
• Configure iframe allow attributes consistently with the top-level policy.
• Remember that Permissions Policy does not replace user permission controls.
• Remember that Permissions Policy does not replace authentication or authorization.
• Check secure-context requirements for sensitive browser APIs.
• Verify the final Permissions-Policy response header.
• Test the policy in the browsers that the application supports.
• Review old Feature-Policy examples before using them in a current project.

Frequently Asked Questions

Helpful Security Header Tools

A Permissions Policy Generator can help build a Permissions-Policy header for selected browser features and origins. A Security Headers Generator is useful when configuring Permissions Policy together with other HTTP security headers.

An HTTP Header Generator can help assemble a complete set of response headers, while a Referrer Policy Generator can configure referrer disclosure separately. A CSP Header Builder is useful for configuring Content Security Policy alongside Permissions Policy.

Conclusion

Permissions Policy gives websites a way to control access to selected browser capabilities. Instead of allowing every feature by default, an application can explicitly disable capabilities it does not use and delegate required features only to appropriate embedded origins.

The most important concepts are feature allowlists, the Permissions-Policy HTTP header, iframe delegation through allow, the distinction between browser permissions and policy restrictions, and the difference between Permissions Policy and other security mechanisms such as CSP and CORS.

A practical configuration should follow the principle of least privilege: identify the browser capabilities the application actually needs, restrict unnecessary features, explicitly review third-party embeds and verify the final policy in the deployed environment.