本頁面由 Cloud Translation API 翻譯而成。

使用權限政策控管瀏覽器功能

管理網頁和第三方 iframe 對瀏覽器功能的存取權。

Kevin K. Lee

權限政策 (舊稱「功能政策」) 可讓開發人員控制網頁可用的瀏覽器功能、 iframe 和子資源，方法是宣告一組政策，讓瀏覽器強制執行。這些政策會套用至回應標頭來源清單中提供的來源。來源清單可以包含相同來源和/或跨來源，因此允許開發人員可控管第一方和第三方的瀏覽器功能存取權。

使用者必須最終決定允許存取更強大的功能，也必須透過提示提供明確權限。

權限政策可讓頂層網站定義網站和第三個網站「協議」和「監控」功能存取權要求是否合法。例如：封鎖所有第三方的地理位置功能開發人員可以確定沒有第三方地理位置。

注意： Privacy Sandbox 是一系列提案和 API，可在不使用第三方 Cookie 或其他追蹤機制的情況下，滿足第三方使用情境。 User-Agent Client Hints 和 Topics API 等 Privacy Sandbox API 是由權限政策管理，就像管理 geolocation 和 camera 等功能一樣。如需需要權限政策的網路平台 API 清單，請參閱功能清單。請注意，這份清單可能不符現況。

權限政策變更

權限政策先前稱為功能政策。主要概念仍維持不變，但名稱上有一些重要異動。

結構化欄位使用方式

結構化欄位提供一組常見的資料結構，可用於將 HTTP 標頭欄位值的剖析和序列化作業標準化。如要進一步瞭解結構化欄位，請參閱 Fastly 的網誌文章「透過結構化標頭欄位改善 HTTP」。

舊優惠

  geolocation 'self' https://example.com; camera 'none'

使用功能政策之前。

新功能

  geolocation=(self "https://example.com"), camera=()

新增權限政策。

使用 iframe `allow` 屬性合併標頭

透過功能政策，您可以將來源加入標頭來源清單，或在 iframe 標記中加入 allow 屬性，即可將這項功能新增至跨來源頁框。使用權限政策時，如果您在來源清單中加入跨來源頁框，該來源的 iframe 標記就必須包含 allow 屬性。如果回應中沒有權限政策標頭，系統會將來源清單視為預設值為 *。在 iframe 中加入 allow 屬性即可使用這項功能。

因此，我們建議開發人員在回應中明確設定權限政策標頭，讓未列在來源清單中的跨來源 iframe 都無法存取這項功能，即使 allow 存在也一樣。

Chrome 第 88 版後仍可使用功能政策，但可做為權限政策的別名。除語法外，邏輯沒有差異。如果同時使用權限政策和功能政策標頭，Permissions-Policy 標頭的優先順序將較高，並會覆寫 Feature-Policy 標頭提供的值。

如何使用權限政策？

快速總覽

在深入探討前，我們先快速看一下以下這個常見情況：身為網站擁有者，並想控管網站和第三方程式碼使用瀏覽器功能的方式。

您的網站https://your-site.example。
你的網站嵌入了來源相同來源 (https://your-site.example) 的 iframe。
你的網站嵌入了你所信任的 https://trusted-site.example 的 iframe。
您的網站也會顯示 https://ad.example 放送的廣告。
您只需允許網站和信任的網站地理位置，而不允許廣告刊登。

在此情況下，請使用下列標頭：

Permissions-Policy: geolocation=(self "https://trusted-site.example")

接著，請明確將 allow 屬性設為受信任網站的 iframe 標記：

<iframe src="https://trusted-site.example" allow="geolocation">

權限政策使用情形的快速總覽圖表。

在本例中，標頭來源清單只允許你的網站 (self) 和 trusted-site.example 使用地理位置功能。「ad.example」無法使用地理位置。

您的網站 (your-site.example) 已取得使用者同意，可以使用地理位置功能。
同來源 iframe (your-site.example) 可以在不使用 allow 屬性的情況下使用此功能。
如果 iframe 是由另一個子網域 (subdomain.your-site-example) 放送，但並未加入來源清單，而在 iframe 代碼上設定了 allow 屬性，則無法使用這項功能。系統會將不同的子網域視為跨來源網站，但屬於跨來源網站。
凡是加入來源清單，並在 iframe 代碼上設定了 allow 屬性的跨來源 iframe (trusted-site.example)，才能使用這項功能。
在來源清單中加入的跨來源 iframe (trusted-site.example) 沒有 allow 屬性，因此無法使用這項功能。
系統會禁止未加入來源清單的跨來源 iframe (ad.example) 使用這項功能，即使 iframe 代碼中包含 allow 屬性也一樣。

`Permissions-Policy` HTTP 回應標頭

使用者提出要求後，伺服器會回應權限政策標頭，然後瀏覽器會根據該標頭授予存取權。

Permissions-Policy: &lt;feature&gt;=(&lt;token&gt;|&lt;origin(s)&gt;)

在伺服器的回應中使用 Permissions-Policy 標頭，即可設定地圖項目的允許來源。標頭值可以包含符記和來源字串的組合。所有來源的可用權杖都是*可用權杖，self則代表相同來源。

如果標題涉及多項地圖項目，請以半形逗號隔開各個地圖項目。如果您列出多個來源，請以空格分隔來源清單中的每個來源。如果標頭列出的是跨來源要求的來源，iframe 代碼必須包含 allow 屬性。

以下為部分鍵/值組合範例：

語法：[FEATURE]=*
- 政策適用於所有來源
- 範例：geolocation=*
語法：[FEATURE]=(self)
- 套用至相同來源的政策
- 範例：geolocation=(self)
語法：[FEATURE]=(self [ORIGIN(s)])
- 政策已套用至相同來源與指定來源
- 範例：geolocation=(self "https://a.example" "https://b.example")
- self 是「https://your-site.example」的簡寫
語法：[FEATURE]=([ORIGIN(s)])
- 政策已套用至相同來源與指定來源
- 範例：geolocation=("https://your-site.example" "https://a.example" "https://b.example")
- 使用這種語法時，其中一個來源應為嵌入器的來源。此外，如果嵌入網頁本身未獲得權限，即使將 iframe 加入來源清單，該頁面嵌入的 iframe 也會遭到封鎖，這是因為這類 iframe 會委派權限。您也可以使用 self 權杖。
語法：[FEATURE]=()
- 已禁止所有來源使用這項功能
- 範例：geolocation=()

，瞭解如何調查及移除這項存取權。

警告：如果回應中沒有「權限政策」標頭，則會使用預設值 * 權杖。如此一來，網頁上所有含有 allow 屬性的 iframe 就能使用這項功能。因此，強烈建議您在 Permissions-Policy 標頭中明確設定來源清單，藉此控管存取權。

重點：調整功能政策的權限政策異動後，將來源新增至標頭來源清單已無法再啟用這項功能。如果 iframe 是跨來源，無論標頭來源清單中的設定為何，都必須加入 allow 屬性。

不同的子網域和路徑

系統會將不同的子網域 (例如 https://your-site.example 和 https://subdomain.your-site.example) 視為「相同網站，但跨來源」。因此，在來源清單中新增子網域，並不會允許存取同一個網站的其他子網域。凡是需要使用這項功能的內嵌子網域，都必須個別加入來源清單。舉例來說，如果只允許透過標頭 Permissions-Policy: browsing-topics=(self) 存取使用者的瀏覽主題，那麼來自同一個網站不同子網域的 iframe 就無法存取主題。https://subdomain.your-site.example

系統會將不同路徑 (例如 https://your-site.example 和 https://your-site.example/embed) 視為相同來源，而且不同的路徑不必列在來源清單中。

iframe `allow` 屬性

iframe 設定

跨來源使用時，iframe 需要代碼中的 allow 屬性才能存取這項功能。

語法：<iframe src="[ORIGIN]" allow="[FEATURE] <'src' | [ORIGIN(s)]"></iframe>

例如：

<iframe src="https://trusted-site.example" allow="geolocation">

敬上

注意：allow="geolocation" 語法是 allow="geolocation 'src' 的簡寫。src 是一種特殊符記，會展開為 iframe 的 src 屬性來源。

處理 iframe 瀏覽作業

iframe 導覽設定

根據預設，如果 iframe 前往其他來源，這項政策就不會套用至 iframe 前往的來源。只要在 allow 屬性中列出 iframe 前往的來源，系統就會將先前 iframe 套用的權限政策套用至 iframe 前往的來源。

<iframe src="https://trusted-site.example" allow="geolocation https://trusted-site.example https://trusted-navigated-site.example">

如要查看實際運作情形，請前往 iframe 導覽示範。

權限政策設定範例

以下示範提供下列設定範例。

允許所有來源使用這項功能

可存取這項功能的所有來源架構

Permissions-Policy: geolocation=*

<iframe src="https://trusted-site.example" allow="geolocation">
<iframe src="https://ad.example" allow="geolocation">

將來源清單設為 * 符記後，就能對網頁上所有的來源 (包括本身和所有 iframe) 使用這項功能。在本例中，所有透過 https://your-site.example 提供的程式碼，以及從 https://trusted-site.example iframe 和 https://ad.example 提供的代碼，都可存取使用者瀏覽器中的地理位置功能。請記住，您必須在 iframe 上設定 allow 屬性，並且將來源新增至標頭來源清單。

您可以在示範中查看這項設定。

功能僅適用於來源相同

僅允許相同來源的架構存取功能

Permissions-Policy: geolocation=(self)

使用 self 權杖只允許將地理位置用於相同出發地。跨來源將無法存取這項功能。在本例中，只有 https://trusted-site.example (self) 可存取地理位置。如果只想在您的網頁上找到這項功能，請使用這個語法。

您可以在示範中查看這項設定。

允許存取相同來源和特定跨來源的功能

可存取功能的指定來源架構

Permissions-Policy: geolocation=(self "https://trusted-site.example")

這個語法允許本身 (https://your-site.example) 和 https://trusted-site.example 使用地理位置。請記得在 iframe 代碼中明確加入 allow 屬性。如果另一個包含 <iframe src="https://ad.example" allow="geolocation"> 的 iframe，則 https://ad.example 將無法存取地理位置功能。只有列於來源清單中列出的原始網頁和 https://trusted-site.example，且 iframe 標記中含有 allow 屬性，才能存取使用者的功能。

您可以在示範中查看這項設定。

已禁止所有來源使用這項功能

禁止存取這項功能的所有來源架構

Permissions-Policy: geolocation=()

如果來源清單空白，則所有來源都會無法使用這項功能。您可以在示範中查看這項設定。

使用 JavaScript API

功能政策的現有 JavaScript API 會以物件的形式顯示在文件或元素 (document.featurePolicy or element.featurePolicy) 上。尚未實作權限政策的 JavaScript API。

Feature Policy API 可用於權限政策設定的政策，但有一些限制。關於 JavaScript API 實作，您還有其他問題，而我們準備了提案，協助您將邏輯移至 Permissions API。如有任何想法，歡迎加入討論。

featurePolicy.allowsFeature(feature)

如果此功能可用於預設來源用途，則傳回 true。
兩種政策的行為與「權限政策」和舊版功能政策相同
在 iframe 元素 (iframeEl.featurePolicy.allowsFeature('geolocation')) 上呼叫 allowsFeature() 時，傳回的值會反映 iframe 中是否設定了 allow 屬性

featurePolicy.allowsFeature(feature, origin)

如果指定來源允許此功能，則傳回 true。
如果已在 document 上呼叫此方法，此方法不會再指出是否允許指定來源使用此功能，例如功能政策。現在，這個方法會指示該來源可能允許該功能。您必須額外檢查 iframe 是否已設定 allow 屬性。開發人員必須對 iframe 元素上的 allow 屬性進行額外檢查，以判定第三方來源是否可以使用這項功能。

使用 `element` 物件檢查 iframe 中的功能

您可以使用 element.allowsFeature(feature)，將 allow 屬性納入考量，這一點與不需要的 document.allowsFeature(feature, origin) 不同。

const someIframeEl = document.getElementById('some-iframe')
const isCameraFeatureAllowed = someIframeEl.featurePolicy.allowsFeature('camera')

featurePolicy.allowedFeatures()

傳回適用於預設來源用途的功能清單。
兩項權限政策和功能政策設定的行為皆相同
如果相關節點是 iframe，系統會將 allow 屬性納入考量。

featurePolicy.features()

傳回瀏覽器可用功能清單。
兩項權限政策和功能政策設定的行為皆相同

Chrome 開發人員工具整合

Chrome 開發人員工具與權限政策的整合

瞭解開發人員工具中的權限政策如何運作。

開啟 Chrome 開發人員工具。
開啟「應用程式」面板查看每個頁框許可和禁止的功能。
在側欄中，選取要檢查的頁框。系統會列出所選影格可使用的功能，以及該影格中封鎖的功能清單。

從功能政策遷移

如果您目前正在使用 Feature-Policy 標頭，可以按照下列步驟改用權限政策。

將功能政策標頭替換為權限政策標頭

由於功能政策標頭僅適用於以 Chromium 為基礎的瀏覽器，且自 Chrome 88 版開始支援權限政策標頭，因此你可以放心透過權限政策更新現有的標頭。

舊優惠

Feature-Policy:
  autoplay *;
  geolocation 'self';
  camera 'self' 'https://trusted-site.example';
  fullscreen 'none';

使用功能政策之前。

新功能

Permissions-Policy:
  autoplay=*,
  geolocation=(self),
  camera=(self "https://trusted-site.example"),
  fullscreen=()

新增權限政策。

更新「`document.allowsFeature(feature, origin)`」用量

如果您使用 document.allowsFeature(feature, origin) 方法檢查 iframe 允許的功能，請使用 iframe 元素附加的 allowsFeature(feature) 方法，不要使用所含 document。element.allowsFeature(feature) 方法負責允許屬性，document.allowsFeature(feature, origin) 則不需要。

正在檢查「`document`」功能存取權

如要繼續使用 document 做為基本節點，您必須為 iframe 標記上的 allow 屬性進行額外檢查。

<iframe id="some-iframe" src="https://example.com" allow="camera"></iframe>

Permissions-Policy: camera=(self "https://example.com")

const isCameraPolicySet = document.featurePolicy.allowsFeature('camera', 'https://example.com')

const someIframeEl = document.getElementById('some-iframe')
const hasCameraAttributeValue = someIframeEl.hasAttribute('allow')
&& someIframeEl.getAttribute('allow').includes('camera')

const isCameraFeatureAllowed = isCameraPolicySet && hasCameraAttributeValue

建議您像上述範例一樣，對 element 物件呼叫 allowsFeature()，而不要使用 document 更新現有程式碼。

Reporting API

Reporting API 為網頁應用程式提供一致的回報機制，而權限政策違規的 Reporting API 仍是實驗功能。

如要測試實驗功能，請按照逐步操作說明操作，並在 chrome://flags/#enable-experimental-web-platform-features 中啟用標記。啟用旗標後，您可以在開發人員工具中的「應用程式」分頁，觀察「工具」中違反權限政策的情形：

以下例子說明如何建構 Reporting API 標頭：

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;

在目前的實作中，您可以設定「default」端點，接收在該影格內發生任何違規情況的報告(如上方範例所示)子頁框必須自行設定報表設定。

瞭解詳情

如要進一步瞭解權限政策，請參閱下列資源：

使用權限政策控管瀏覽器功能

權限政策變更

結構化欄位使用方式

使用 iframe allow 屬性合併標頭

如何使用權限政策？

快速總覽

Permissions-Policy HTTP 回應標頭

不同的子網域和路徑

iframe allow 屬性

處理 iframe 瀏覽作業

權限政策設定範例

允許所有來源使用這項功能

功能僅適用於來源相同

允許存取相同來源和特定跨來源的功能

已禁止所有來源使用這項功能

使用 JavaScript API

featurePolicy.allowsFeature(feature)

featurePolicy.allowsFeature(feature, origin)

使用 element 物件檢查 iframe 中的功能

featurePolicy.allowedFeatures()

featurePolicy.features()

Chrome 開發人員工具整合

從功能政策遷移

將功能政策標頭替換為權限政策標頭

更新「document.allowsFeature(feature, origin)」用量

正在檢查「document」功能存取權

Reporting API

瞭解詳情

使用 iframe `allow` 屬性合併標頭

`Permissions-Policy` HTTP 回應標頭

iframe `allow` 屬性

使用 `element` 物件檢查 iframe 中的功能

更新「`document.allowsFeature(feature, origin)`」用量

正在檢查「`document`」功能存取權