Firefox Tomorrow

http header

Permissions-Policy header

View on MDN ↗

Limited availability

The HTTP Permissions-Policy response header provides a mechanism to allow and deny the use of browser features in a document or within any <iframe> elements in the document.

Violations of a policy can be reported using the Reporting API. Reports may be sent to a server indicated by name in a per-directive report-to parameter, or otherwise to the server endpoint named "default" (the mapping between server endpoint names and URLs is set using the Reporting-Endpoints HTTP response header). Reports can also be observed in the page for which the policy is being enforced using a ReportingObserver. The format of the report and additional detail is provided in PermissionsPolicyViolationReport.

For more information, see the main Permissions Policy article.

Header type [Response header](https://developer.mozilla.org/en-US/docs/Glossary/Response%20header)

Syntax

# Single directive
Permissions-Policy: <directive>=<allowlist>

# Single directive with reporting endpoint
Permissions-Policy: <directive>=<allowlist>;report-to=<endpoint>

# Multiple directives, with and without server reporting endpoints
Permissions-Policy: <directive>=<allowlist>, <directive>=<allowlist>;report-to=<endpoint>, ...

The header can be used to set the allowlists for one or more directives, and optionally a per-directive report-to parameter indicating the server endpoint to send policy violation reports to. The entries for each directive are comma separated.

  • <directive>

    • : The Permissions Policy directive to apply the allowlist to. See Directives below for a list of the permitted directive names.

  • <allowlist>

    • : An allowlist is a list of origins that takes one or more of the following values contained in parentheses, separated by spaces:

      • * (wildcard)
        • : The feature will be allowed in this document, and all nested browsing contexts (<iframe>s) regardless of their origin.
      • () (empty allowlist)
        • : The feature is disabled in top-level and nested browsing contexts. The equivalent for <iframe> allow attributes is 'none'.
      • self
        • : The feature will be allowed in this document, and in all nested browsing contexts (<iframe>s) in the same origin only. The feature is not allowed in cross-origin documents in nested browsing contexts. self can be considered shorthand for https://your-site.example.com. The equivalent for <iframe> allow attributes is self.
      • src
        • : The feature will be allowed in this <iframe>, as long as the document loaded into it comes from the same origin as the URL in its <src> attribute. This value is only used in the <iframe> allow attribute, and is the default allowlist value in <iframe>s.
      • "<origin>"
        • : The feature is allowed for specific origins (for example, "https://a.example.com"). Origins should be separated by spaces. Note that origins in <iframe> allow attributes are not quoted.

      The values * and () may only be used on their own, while self and src may be used in combination with one or more origins.

      [!NOTE] Directives have a default allowlist, which is always one of *, self, or none for the Permissions-Policy HTTP header, and governs the default behavior if they are not explicitly listed in a policy. These are specified on the individual directive reference pages. For <iframe> allow attributes, the default behavior is always src.

  • report-to=<endpoint> Optional

    • : The report-to parameter can be used to indicate the name of a reporting endpoint where reports will be sent if there is a policy violation for the associated directive. The endpoint name and its associated URL must be specified in a separate Reporting-Endpoints HTTP response header.

      If omitted, reports will be send to the default reporting endpoint if one has been defined. See Reporting API for more information.

Where supported, you can include wildcards in Permissions Policy origins. This means that instead of having to explicitly specify several different subdomains in an allowlist, you can specify them all in a single origin with a wildcard.

So instead of:

("https://example.com" "https://a.example.com" "https://b.example.com" "https://c.example.com")

You can specify:

("https://example.com" "https://*.example.com")

[!NOTE] "https://*.example.com" does not match "https://example.com".

Directives

Examples

Basic usage

Permissions-Policy header

To allow all origins access to geolocation, you would do this:

Permissions-Policy: geolocation=*

Or to allow access to a subset of origins, you’d do this:

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

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.

For example, the following are equivalent:

Permissions-Policy: picture-in-picture=(), geolocation=(self https://example.com/), camera=*

Permissions-Policy: picture-in-picture=()
Permissions-Policy: geolocation=(self https://example.com/)
Permissions-Policy: camera=*

iframes

For an <iframe> to have a feature enabled its allowed origin must also be in the allowlist for the parent page. 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>.

To allow all origins access to geolocation, you would do this:

<iframe src="https://example.com" allow="geolocation *"></iframe>

To apply a policy to the current origin and others, you’d do this:

<iframe
  src="https://example.com"
  allow="geolocation 'self' https://a.example.com https://b.example.com"></iframe>

This is important: By default, if an <iframe> navigates to another origin, the policy is not applied to the origin that the <iframe> navigates to. By listing the origin that the <iframe> navigates to in the allow attribute, the Permissions Policy that was applied to the original <iframe> will be applied to the origin the <iframe> navigates to.

Several features can be controlled at the same time by including a semi-colon-separated list of policy directives inside the allow attribute.

<iframe
  src="https://example.com"
  allow="geolocation 'self' https://a.example.com https://b.example.com; fullscreen 'none'"></iframe>

It is worth giving the src value a special mention. We mentioned above that using this allowlist value will mean that the associated feature will be allowed in this <iframe>, as long as the document loaded into it comes from the same origin as the URL in its <src> attribute. This value is the default allowlist value for features listed in allow, so the following are equivalent:

<iframe src="https://example.com" allow="geolocation 'src'"></iframe>
<iframe src="https://example.com" allow="geolocation"></iframe>

Denying access to powerful features

SecureCorp Inc. wants to disable Microphone (for example getUserMedia()) and Geolocation APIs in its application. It can do so using the following response header:

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

By specifying () for the origin list, the specified features will be disabled for all browsing contexts (this includes all <iframe>s), regardless of their origin.

Combining HTTP header and <iframe> policies

For example, let’s say that we wanted to enable geolocation usage on our own origin, and in embedded content coming from our trusted ad network. We could set up the page-wide Permissions Policy like this:

Permissions-Policy: geolocation=(self https://trusted-ad-network.com)

Over in our ad <iframe>s, we could set access to the https://trusted-ad-network.com origin like this:

<iframe src="https://trusted-ad-network.com" allow="geolocation"></iframe>

If a different origin ended up getting loaded into <iframe>, it would not have access to geolocation:

<iframe src="https://rogue-origin-example.com" allow="geolocation"></iframe>

Reporting violations

This example shows how to configure reporting of Permissions-Policy violations to a server endpoint.

The response headers below block geolocation and define the reporting endpoint name for the feature as “geo_endpoint”. The Reporting-Endpoints HTTP response header is used to define the URL of this endpoint name.

Reporting-Endpoints: geo_endpoint="https://example.com/reports"
Permissions-Policy: geolocation=();report-to=geo_endpoint

[!NOTE] To send all violation reports to the same endpoint we might instead define the "default" reporting endpoint:

Reporting-Endpoints: default="https://example.com/reports"
Permissions-Policy: geolocation=()

A violation occurs when a page attempts to use the blocked feature, for example:

navigator.geolocation.getCurrentPosition(
  () => {},
  () => {},
);

The report payload sent to the endpoint might look like this:

[
  {
    "age": 48512,
    "body": {
      "columnNumber": 29,
      "disposition": "enforce",
      "lineNumber": 44,
      "message": "Permissions policy violation: geolocation access has been blocked because of a permissions policy applied to the current document.",
      "featureId": "geolocation",
      "sourceFile": "https://example.com/"
    },
    "type": "permissions-policy-violation",
    "url": "https://example.com/",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36"
  }
]

[!NOTE] Chrome’s server-side serialization of violation reports uses policyId rather than featureId for the feature name in the body of a server report. The PermissionsPolicyViolationReport returned by a ReportingObserver follows the specification.

Specifications

SpecificationsStandards references are available on the canonical MDN page.

Browser compatibility

Browser compatibilityCompatibility data is available on the canonical MDN page.

See also