許可權策略

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。

在支援的情況下，您可以在許可權策略來源中包含萬用字元。這意味著，您不必在允許列表中顯式指定多個不同的子域，而是在一個帶有萬用字元的來源中指定它們。

所以，代替

("https://example.com" "https://a.example.com" "https://b.example.com" "https://c.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 標頭

要允許所有來源訪問地理位置，您可以執行以下操作

Permissions-Policy: geolocation=*

或者，要允許訪問一組來源，您可以執行以下操作

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

透過傳送包含以逗號分隔的策略列表的標頭或為每個策略傳送單獨的標頭，可以同時控制多個功能。

例如，以下等效

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> 中指定所需的子集支援。

要允許所有來源訪問地理位置，您可以執行以下操作

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

要將策略應用於當前來源和其他來源，您可以執行以下操作

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

這一點很重要：預設情況下，如果 <iframe> 導航到另一個來源，則不會將策略應用於 <iframe> 導航到的來源。透過在 allow 屬性中列出 <iframe> 導航到的來源，應用於原始 <iframe> 的許可權策略將應用於 <iframe> 導航到的來源。

可以透過在 allow 屬性中包含以分號分隔的策略指令列表，同時控制多個功能。

<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 值，因此以下等效

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

SecureCorp Inc. 想要在應用程式中停用麥克風（例如 MediaDevices.getUserMedia()）和 Geolocation API。它可以使用以下響應標頭來實現這一點

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

透過為來源列表指定 ()，指定的功能將被停用，適用於所有瀏覽上下文（包括所有 <iframe>），無論其來源如何。

例如，假設我們想要在自己的來源和來自我們信任的廣告網路的嵌入內容中啟用地理位置使用。我們可以這樣設定頁面範圍的許可權策略

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

在我們的廣告 <iframe> 中，我們可以這樣設定對 https://trusted-ad-network.com 來源的訪問許可權

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

如果其他來源最終載入到 <iframe> 中，則它將無法訪問地理位置

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

• 許可權策略
• Document.featurePolicy 和 FeaturePolicy
• Content-Security-Policy
• Referrer-Policy