Feature-Policy
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
Warning: The header has now been renamed to Permissions-Policy
in the spec, and this article will eventually be updated to reflect that change.
The HTTP Feature-Policy
header provides a mechanism to allow and deny the use of browser features in its own frame, and in content within any <iframe>
elements in the document.
For more information, see the main Feature Policy article.
Header type | Response header |
---|---|
Forbidden header name | yes |
Syntax
Feature-Policy: <directive> <allowlist>
<directive>
-
The Feature 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, separated by spaces:*
: The feature will be allowed in this document, and all nested browsing contexts (iframes) regardless of their origin.'self'
: The feature will be allowed in this document, and in all nested browsing contexts (iframes) in the same origin. The feature is not allowed in cross-origin documents in nested browsing contexts.'src'
: (In an iframeallow
attribute only) 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 the iframe's src attribute.Note: The
'src'
origin is used in the iframeallow
attribute only, and is the defaultallowlist
value.'none'
: The feature is disabled in top-level and nested browsing contexts.- <origin(s)>: The feature is allowed for specific origins (for example, https://example.com). Origins should be separated by a space.
The values
*
(enable for all origins) or'none'
(disable for all origins) may only be used alone, while'self'
and'src'
may be used with one or more origins.Features have a default allowlist, which is one of:
*
,'self'
, or'none'
.
Directives
accelerometer
-
Controls whether the current document is allowed to gather information about the acceleration of the device through the
Accelerometer
interface. ambient-light-sensor
-
Controls whether the current document is allowed to gather information about the amount of light in the environment around the device through the
AmbientLightSensor
interface. autoplay
-
Controls whether the current document is allowed to autoplay media requested through the
HTMLMediaElement
interface. When this policy is disabled and there were no user gestures, thePromise
returned byHTMLMediaElement.play()
will reject with aDOMException
. The autoplay attribute on<audio>
and<video>
elements will be ignored. battery
-
Controls whether the use of the Battery Status API is allowed. When this policy is disabled, the
Promise
returned byNavigator.getBattery()
will reject with aNotAllowedError
DOMException
. camera
-
Controls whether the current document is allowed to use video input devices. When this policy is disabled, the
Promise
returned bygetUserMedia()
will reject with aNotAllowedError
DOMException
. display-capture
-
Controls whether or not the current document is permitted to use the
getDisplayMedia()
method to capture screen contents. When this policy is disabled, the promise returned bygetDisplayMedia()
will reject with aNotAllowedError
if permission is not obtained to capture the display's contents. document-domain
-
Controls whether the current document is allowed to set
document.domain
. When this policy is disabled, attempting to setdocument.domain
will fail and cause aSecurityError
DOMException
to be thrown. encrypted-media
-
Controls whether the current document is allowed to use the Encrypted Media Extensions API (EME). When this policy is disabled, the
Promise
returned byNavigator.requestMediaKeySystemAccess()
will reject with aDOMException
. execution-while-not-rendered
-
Controls whether tasks should execute in frames while they're not being rendered (e.g. if an iframe is
hidden
ordisplay: none
). execution-while-out-of-viewport
-
Controls whether tasks should execute in frames while they're outside of the visible viewport.
fullscreen
-
Controls whether the current document is allowed to use
Element.requestFullScreen()
. When this policy is disabled, the returnedPromise
rejects with aTypeError
. gamepad
-
Controls whether the current document is allowed to use the Gamepad API. When this policy is disabled, calls to
Navigator.getGamepads()
will throw aSecurityError
DOMException
, and thegamepadconnected
andgamepaddisconnected
events will not fire. geolocation
-
Controls whether the current document is allowed to use the
Geolocation
Interface. When this policy is disabled, calls togetCurrentPosition()
andwatchPosition()
will cause those functions' callbacks to be invoked with aGeolocationPositionError
code ofPERMISSION_DENIED
. gyroscope
-
Controls whether the current document is allowed to gather information about the orientation of the device through the
Gyroscope
interface. layout-animations
-
Controls whether the current document is allowed to show layout animations.
legacy-image-formats
-
Controls whether the current document is allowed to display images in legacy formats.
magnetometer
-
Controls whether the current document is allowed to gather information about the orientation of the device through the
Magnetometer
interface. microphone
-
Controls whether the current document is allowed to use audio input devices. When this policy is disabled, the
Promise
returned byMediaDevices.getUserMedia()
will reject with aNotAllowedError
. midi
-
Controls whether the current document is allowed to use the Web MIDI API. When this policy is disabled, the
Promise
returned byNavigator.requestMIDIAccess()
will reject with aDOMException
. -
Controls the availability of mechanisms that enables the page author to take control over the behavior of spatial navigation, or to cancel it outright.
oversized-images
-
Controls whether the current document is allowed to download and display large images.
payment
-
Controls whether the current document is allowed to use the Payment Request API. When this policy is enabled, the
PaymentRequest()
constructor will throw aSecurityError
DOMException
. picture-in-picture
-
Controls whether the current document is allowed to play a video in a Picture-in-Picture mode via the corresponding API.
publickey-credentials-get
-
Controls whether the current document is allowed to use the Web Authentication API to retrieve already stored public-key credentials, i.e. via
navigator.credentials.get({publicKey: ..., ...})
. speaker-selection
-
Controls whether the current document is allowed to use the Audio Output Devices API to list and select speakers.
sync-xhr
-
Controls whether the current document is allowed to make synchronous
XMLHttpRequest
requests. unoptimized-images
-
Controls whether the current document is allowed to download and display unoptimized images.
unsized-media
-
Controls whether the current document is allowed to change the size of media elements after the initial layout is complete.
usb
-
Controls whether the current document is allowed to use the WebUSB API.
screen-wake-lock
-
Controls whether the current document is allowed to use Screen Wake Lock API to indicate that device should not turn off or dim the screen.
-
Controls whether or not the current document is allowed to use the
Navigator.share()
of Web Share API to share text, links, images, and other content to arbitrary destinations of user's choice, e.g. mobile apps. xr-spatial-tracking
-
Controls whether or not the current document is allowed to use the WebXR Device API to interact with a WebXR session.
Example
SecureCorp Inc. wants to disable Microphone and Geolocation APIs in its application. It can do so by delivering the following HTTP response header to define a feature policy:
Feature-Policy: microphone 'none'; geolocation 'none'
By specifying the 'none'
keyword for the origin list, the specified features will be disabled for all browsing contexts (this includes all iframes), regardless of their origin.
Specifications
Specification |
---|
Permissions Policy # permissions-policy-http-header-field |
Browser compatibility
BCD tables only load in the browser