权限策略

HTTP Permissions-Policy 头部提供了一种机制，允许或拒绝在文档或文档中任何 <iframe> 元素中使用浏览器功能。

有关更多信息，请参阅主要权限策略文章。

头部类型	响应头部
禁止的头部名称	是

语法

http

Permissions-Policy: <directive>=<allowlist>

<directive>

要应用 allowlist 的权限策略指令。有关允许的指令名称列表，请参见下面的指令。

<allowlist>

允许列表是一个包含一个或多个以下值的列表，这些值包含在括号中，并用空格隔开

*：该功能将在本文档以及所有嵌套的浏览上下文 (<iframe>) 中被允许，无论其来源如何。
()（空允许列表）：该功能在顶级和嵌套的浏览上下文中被禁用。对于 <iframe> allow 属性，等效项是 'none'。
self：该功能将在本文档以及所有与本文档来源相同的嵌套浏览上下文 (<iframe>) 中被允许。该功能在嵌套浏览上下文中的跨来源文档中不被允许。self 可以被视为 https://your-site.example.com 的简写。对于 <iframe> allow 属性，等效项是 self。
src：该功能将在该 <iframe> 中被允许，只要加载到其中的文档来自其 src 属性中 URL 的相同来源。此值仅用于 <iframe> allow 属性，并且是 <iframe> 中的默认 allowlist 值。
"<origin>"：该功能允许特定来源（例如，"https://a.example.com"）。来源之间应使用空格隔开。请注意，<iframe> 允许属性中的来源没有引号。

* 和 () 值只能单独使用，而 self 和 src 可以与一个或多个来源结合使用。

注意： 指令有一个默认允许列表，它始终是 Permissions-Policy HTTP 头部的 *、self 或 none 之一，并在它们没有明确列在策略中时控制默认行为。这些在各个指令参考页面上指定。对于 <iframe> allow 属性，默认行为始终是 src。

在支持的情况下，您可以在权限策略来源中包含通配符。这意味着，您不必在允许列表中显式指定多个不同的子域，而是在一个带有通配符的来源中指定它们。

所以，代替

http

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

您可以指定

http

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

注意： "https://*.example.com" 不匹配 "https://example.com"。

指令

accelerometer Experimental: 控制当前文档是否被允许通过 Accelerometer 接口收集有关设备加速度的信息。
ambient-light-sensor Experimental: 控制当前文档是否被允许通过 AmbientLightSensor 接口收集有关设备周围环境光线量的信息。
attribution-reporting Experimental: 控制当前文档是否被允许使用归因报告 API。
autoplay Experimental: 控制当前文档是否被允许自动播放通过 HTMLMediaElement 接口请求的媒体。当此策略被禁用且没有用户手势时，由 Promise 返回的 HTMLMediaElement.play() 将使用 NotAllowedError DOMException 拒绝。<audio> 和 <video> 元素上的自动播放属性将被忽略。
bluetooth Experimental: 控制是否允许使用 Web 蓝牙 API。当此策略被禁用时，由 Navigator.bluetooth 返回的 Bluetooth 对象的方法将返回 false 或拒绝返回的 Promise，并使用 SecurityError DOMException。
browsing-topics Experimental Non-standard: 控制对主题 API 的访问。如果策略明确禁止使用主题 API，则任何尝试调用 Document.browsingTopics() 方法或发送带有 Sec-Browsing-Topics 头部的请求都将失败，并使用 NotAllowedError DOMException。
camera: 控制当前文档是否被允许使用视频输入设备。当此策略被禁用时，由 Promise 返回的 getUserMedia() 将使用 NotAllowedError DOMException 拒绝。
compute-pressure Experimental: 控制对计算压力 API 的访问。
display-capture: 控制当前文档是否被允许使用 getDisplayMedia() 方法捕获屏幕内容。当此策略被禁用时，如果未获得捕获显示内容的权限，则由 getDisplayMedia() 返回的 promise 将使用 NotAllowedError DOMException 拒绝。
document-domain Experimental: 控制当前文档是否被允许设置 document.domain。当此策略被禁用时，尝试设置 document.domain 将失败，并导致抛出 SecurityError DOMException。
encrypted-media Experimental: 控制当前文档是否被允许使用加密媒体扩展 API (EME)。当此策略被禁用时，由 Promise 返回的 Navigator.requestMediaKeySystemAccess() 将使用 SecurityError DOMException 拒绝。
fullscreen: 控制当前文档是否被允许使用 Element.requestFullscreen()。当此策略被禁用时，返回的 Promise 将使用 TypeError 拒绝。
gamepad Experimental: 控制当前文档是否被允许使用游戏手柄 API。当此策略被禁用时，对 Navigator.getGamepads() 的调用将抛出 SecurityError DOMException，并且 gamepadconnected 和 gamepaddisconnected 事件将不会触发。
geolocation: 控制当前文档是否被允许使用 Geolocation 接口。当此策略被禁用时，对 getCurrentPosition() 和 watchPosition() 的调用将导致这些函数的回调使用 PERMISSION_DENIED 的 GeolocationPositionError 代码调用。
gyroscope Experimental: 控制当前文档是否被允许通过 Gyroscope 接口收集有关设备方向的信息。
hid Experimental: 控制当前文档是否被允许使用 WebHID API 连接到不常见或奇特的 human interface device，例如备用键盘或游戏手柄。
identity-credentials-get Experimental: 控制当前文档是否允许使用联合凭据管理 API (FedCM)，更具体地说，使用带有 identity 选项的 navigator.credentials.get() 方法。如果此策略禁止使用 API，则 get() 调用返回的 Promise 将会拒绝并抛出 NotAllowedError DOMException。
idle-detection 实验性功能: 控制当前文档是否允许使用空闲检测 API 来检测用户何时与设备交互，例如在聊天应用程序中报告“在线”/“离线”状态。
local-fonts 实验性功能: 控制当前文档是否允许通过 Window.queryLocalFonts() 方法收集用户本地安装的字体信息（另请参阅本地字体访问 API）。
magnetometer 实验性功能: 控制当前文档是否允许通过 Magnetometer 接口收集有关设备方向的信息。
microphone: 控制当前文档是否允许使用音频输入设备。当此策略被禁用时，Promise 将会拒绝并抛出 NotAllowedError DOMException。
midi 实验性功能: 控制当前文档是否允许使用 Web MIDI API。当此策略被禁用时，Promise 将会拒绝并抛出 SecurityError DOMException。
otp-credentials 实验性功能: 控制当前文档是否允许使用 WebOTP API 从应用程序服务器发送的格式特殊的 SMS 消息中请求一次性密码 (OTP)，即通过 navigator.credentials.get({otp: ..., ...})。
payment 实验性功能: 控制当前文档是否允许使用支付请求 API。当此策略被启用时，PaymentRequest() 构造函数将会抛出 SecurityError DOMException。
picture-in-picture 实验性功能: 控制当前文档是否允许通过相应的 API 以画中画模式播放视频。
publickey-credentials-create 实验性功能: 控制当前文档是否允许使用 Web 身份验证 API 创建新的非对称密钥凭据，即通过 navigator.credentials.create({publicKey: ..., ...})。
publickey-credentials-get: 控制当前文档是否允许使用 Web 身份验证 API 检索已存储的公钥凭据，即通过 navigator.credentials.get({publicKey: ..., ...})。
screen-wake-lock: 控制当前文档是否允许使用屏幕唤醒锁定 API 来指示设备不应关闭或调暗屏幕。
serial 实验性功能: 控制当前文档是否允许使用 Web 串行 API 与串行设备进行通信，无论是直接通过串行端口连接，还是通过模拟串行端口的 USB 或蓝牙设备连接。
speaker-selection 实验性功能: 控制当前文档是否允许使用音频输出设备 API 列出和选择扬声器。
storage-access 实验性功能: 控制加载在第三方上下文中的文档（即嵌入在 <iframe> 中）是否允许使用存储访问 API 请求访问非分区 Cookie。
usb 实验性功能: 控制当前文档是否允许使用 WebUSB API。
web-share: 控制当前文档是否允许使用 Navigator.share() 或 Web 共享 API 来将文本、链接、图片和其他内容共享到用户选择的任意目的地，例如移动应用程序。
window-management 实验性功能: 控制当前文档是否允许使用窗口管理 API 来管理多个显示器上的窗口。
xr-spatial-tracking 实验性功能: 控制当前文档是否允许使用 WebXR 设备 API 与 WebXR 会话进行交互。

示例

基本用法

Permissions-Policy 标头

要允许所有来源访问地理位置，您可以执行以下操作

http

Permissions-Policy: geolocation=*

或者，要允许访问一组来源，您可以执行以下操作

http

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

通过发送包含以逗号分隔的策略列表的标头或为每个策略发送单独的标头，可以同时控制多个功能。

例如，以下等效

http

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=*

iframe

对于 <iframe> 要启用某个功能，其允许来源也必须在父页面的允许列表中。由于这种继承行为，建议在 HTTP 标头中指定功能最广泛的可接受支持，然后在每个 <iframe> 中指定所需的子集支持。

要允许所有来源访问地理位置，您可以执行以下操作

html

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

要将策略应用于当前来源和其他来源，您可以执行以下操作

html

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

这一点很重要：默认情况下，如果 <iframe> 导航到另一个来源，则不会将策略应用于 <iframe> 导航到的来源。通过在 allow 属性中列出 <iframe> 导航到的来源，应用于原始 <iframe> 的权限策略将应用于 <iframe> 导航到的来源。

可以通过在 allow 属性中包含以分号分隔的策略指令列表，同时控制多个功能。

html

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

值得特别提及的是 src 值。我们上面提到过，使用此允许列表值意味着此 <iframe> 中将允许关联的功能，只要加载到其中的文档来自与其 src 属性中的 URL 相同的来源。此值是 allow 中列出的功能的默认allowlist 值，因此以下等效

html

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

拒绝访问强大功能

SecureCorp Inc. 想要在应用程序中禁用麦克风（例如 MediaDevices.getUserMedia()）和 Geolocation API。它可以使用以下响应标头来实现这一点

http

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

通过为来源列表指定 ()，指定的功能将被禁用，适用于所有浏览上下文（包括所有 <iframe>），无论其来源如何。

组合 HTTP 标头和 `<iframe>` 策略

例如，假设我们想要在自己的来源和来自我们信任的广告网络的嵌入内容中启用地理位置使用。我们可以这样设置页面范围的权限策略

http

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

在我们的广告 <iframe> 中，我们可以这样设置对 https://trusted-ad-network.com 来源的访问权限

html

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

如果其他来源最终加载到 <iframe> 中，则它将无法访问地理位置

html

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

规范

规范
权限策略 # permissions-policy-http-header-field

浏览器兼容性

BCD 表仅在浏览器中加载