Feature Policy

Feature Policy

Feature Policy allows web developers to selectively enable, disable, and modify the behavior of certain features and APIs in the browser. It is similar to Content Security Policy but controls features instead of security behavior.

Warning: The Feature-Policy header has now been renamed to Permissions-Policy in the spec, and this article will eventually be updated to reflect that change.

In a nutshell

Feature Policy provides a mechanism to explicitly declare what functionality is used (or not used), throughout your website. This allows you to lock in best practices, even as the codebase evolves over time — as well as to more safely compose third-party content — by limiting which features are available.

With Feature Policy, you opt-in to a set of "policies" for the browser to enforce on specific features used throughout a website. These policies restrict what APIs the site can access or modify the browser's default behavior for certain features.

Examples of what you can do with Feature Policy:

  • Change the default behavior of autoplay on mobile and third party videos.
  • Restrict a site from using sensitive devices like the camera, microphone, or speakers.
  • Allow iframes to use the fullscreen API.
  • Block the use of outdated APIs like synchronous XHR and document.write().
  • Ensure images are sized properly and are not too big for the viewport.

Concepts and usage

Feature Policy allows you to control which origins can use which features, both in the top-level page and in embedded frames. Essentially, you write a policy, which is an allowed list of origins for each feature. For every feature controlled by Feature Policy, the feature is only enabled in the current document or frame if its origin matches the allowed list of origins.

For each policy-controlled feature, the browser maintains a list of origins for which the feature is enabled, known as an allowlist. If you do not specify a policy for a feature, then a default allowlist will be used. The default allowlist is specific to each feature.

Writing a policy

A policy is described using a set of individual policy directives. A policy directive is a combination of a defined feature name, and an allowlist of origins that can use the feature.

Specifying your policy

Feature Policy provides two ways to specify policies to control features:

The primary difference between the HTTP header and the allow attribute is that the allow attribute only controls features within an iframe. The header controls features in the response and any embedded content within the page.

For more details see Using Feature Policy.

Inferring the policy

Scripts can programmatically query information about the feature policy via the FeaturePolicy object located at either Document.featurePolicy or HTMLIFrameElement.featurePolicy.

Types of policy-controlled features

Though Feature Policy provides control of multiple features using a consistent syntax, the behavior of policy controlled features varies and depends on several factors.

The general principle is that there should be an intuitive or non-breaking way for web developers to detect or handle the case when the feature is disabled. Newly introduced features may have an explicit API to signal the state. Existing features that later integrate with Feature Policy will typically use existing mechanisms. Some approaches include:

  • Return "permission denied" for JavaScript APIs that require user permission grants.
  • Return false or error from an existing JavaScript API that provides access to feature.
  • Change the default values or options that control the feature behavior.

The current set of policy-controlled features fall into two broad categories:

  • Enforcing best practices for good user experiences.
  • Providing granular control over sensitive or powerful features.

Best practices for good user experiences

There are several policy-controlled features to help enforce best practices for providing good performance and user experiences.

In most cases, the policy-controlled features represent functionality that when used will negatively impact the user experience. To avoid breaking existing web content, the default for such policy-controlled features is to allow the functionality to be used by all origins. Best practices are then enforced by using policies that disable the policy-controlled features. For more details see "Enforcing best practices for good user experiences".

The features include:

  • Layout-inducing animations
  • Legacy image formats
  • Oversized images
  • Synchronous scripts
  • Synchronous XMLHTTPRequest
  • Unoptimized images
  • Unsized media

Granular control over certain features

The web provides functionality and APIs that may have privacy or security risks if abused. In some cases, you may wish to strictly limit how such functionality is used on a website. There are policy-controlled features to allow functionality to be enabled/disabled for specific origins or frames within a website. Where available, the feature integrates with the Permissions API, or feature-specific mechanisms to check if the feature is available.

The features include (see Features list):

  • Accelerometer
  • Ambient light sensor
  • Autoplay
  • Camera
  • Encrypted media
  • Fullscreen
  • Gamepad
  • Geolocation
  • Gyroscope
  • Magnetometer
  • Microphone
  • Midi
  • PaymentRequest
  • Picture-in-picture
  • Speakers
  • USB
  • Web Share API
  • VR / XR

Examples

Specifications

Specification Status Comment
Permissions Policy
The definition of 'Feature-Policy' in that specification.		 Editor's Draft Initial definition. Defines the Feature-Policy header. Directives are defined in the specs for the features they control. See individual directive pages for details.

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
Feature_Policy
60
79
65
No
47
11.1
Only supported through the allow attribute on <iframe> elements.
60
60
65
44
11.3
Only supported through the allow attribute on <iframe> elements.
8.0
accelerometer
67
79
No
No
54
No
67
67
No
48
No
9.0
ambient-light-sensor
67
79
No
No
54
No
67
67
No
48
No
9.0
autoplay
64
79
65
No
51
No
64
64
65
47
No
9.0
battery
No
Will be implemented, see bug 1007264.
No
Will be implemented, see bug 1007264.
No
No
No
No
No
No
Will be implemented, see bug 1007264.
No
No
No
No
camera
60
79
65
No
48
11.1
60
60
65
45
11.3
8.0
display-capture
94
94
67
No
80
No
No
No
67
No
No
No
document-domain
77
79
65
No
64
No
No
No
65
No
No
No
encrypted-media
60
79
65
No
48
No
60
60
65
45
No
8.0
fullscreen
62
79
65
Before Firefox 80, applying fullscreen to an <iframe> (i.e. via the allow attribute) does not work unless the allowfullscreen attribute is also present.
No
49
No
62
62
65
46
No
8.0
gamepad
86
86
91
The default allowlist is * instead of self (as required by the specification).
No
72
No
No
86
91
The default allowlist is * instead of self (as required by the specification).
No
No
No
geolocation
60
79
65
No
47
No
60
60
65
44
No
8.0
gyroscope
67
79
No
No
54
No
67
67
No
48
No
9.0
layout-animations
No
No
No
No
No
No
No
No
No
No
No
No
legacy-image-formats
No
No
No
No
No
No
No
No
No
No
No
No
magnetometer
67
79
No
No
54
No
No
67
No
48
No
9.0
microphone
60
79
65
No
48
11.1
60
60
65
45
11.3
8.0
midi
60
79
65
No
47
No
60
60
65
44
No
8.0
oversized-images
No
No
No
No
No
No
No
No
No
No
No
No
payment
60
79
65
No
47
No
60
60
65
44
No
8.0
picture-in-picture
71
No
No
No
No
No
No
No
No
No
No
No
publickey-credentials-get
84
84
No
No
No
No
84
84
No
No
No
14.0
screen-wake-lock
No
No
No
No
No
No
No
No
No
No
No
No
speaker-selection
No
No
92
No
No
No
No
No
92
No
No
No
sync-xhr
65
79
No
No
52
No
65
65
No
47
No
9.0
unoptimized-images
No
No
No
No
No
No
No
No
No
No
No
No
unsized-media
No
No
No
No
No
No
No
No
No
No
No
No
usb
60
79
No
No
47
No
60
60
No
44
No
8.0
vibrate
No
No
No
No
No
No
No
No
No
No
No
No
vr
62-80
WebVR API was never enabled by default in any production builds and was replaced by WebXR Device API.
79-80
WebVR API was never enabled by default in any production builds and was replaced by WebXR Device API.
No
No
49-67
WebVR API was never enabled by default in any production builds and was replaced by WebXR Device API.
No
No
62-80
WebVR API was never enabled by default in any production builds and was replaced by WebXR Device API.
No
46-true
WebVR API was never enabled by default in any production builds and was replaced by WebXR Device API.
No
8.0-true
WebVR API was never enabled by default in any production builds and was replaced by WebXR Device API.
web-share
No
No
81
Firefox recognizes the web-share permissions policy, but this has no effect in versions of Firefox that do not support the share() method.
No
No
No
No
No
81
Firefox recognizes the web-share permissions policy, but this has no effect in versions of Firefox that do not support the share() method.
No
No
No
xr-spatial-tracking
79
79
No
No
66
No
No
79
No
No
No
12.0

See also

© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/HTTP/Feature_Policy