管理網頁和第三方 iframe 對瀏覽器功能的存取權。
權限政策 (舊稱「功能政策」) 可讓開發人員 控制網頁可用的瀏覽器功能、 iframe 和 子資源,方法是宣告一組政策,讓瀏覽器強制執行。這些 政策會套用至回應標頭來源清單中提供的來源。 來源清單可以包含相同來源和/或跨來源,因此允許 開發人員可控管第一方和第三方的瀏覽器功能存取權。
使用者必須最終決定允許存取更強大的功能,也必須透過提示提供明確權限。
權限政策可讓頂層網站定義網站和第三個網站 「協議」和「監控」 功能存取權要求是否合法。例如: 封鎖所有第三方的地理位置功能 開發人員可以確定沒有第三方 地理位置。
權限政策變更
權限政策先前稱為功能政策。主要概念仍維持不變,但名稱上有一些重要異動。
結構化欄位使用方式
結構化欄位提供一組常見的資料結構,可用於將 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: <feature>=(<token>|<origin(s)>)
在伺服器的回應中使用 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=()
不同的子網域和路徑
系統會將不同的子網域 (例如 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 需要代碼中的 allow
屬性才能存取這項功能。
語法:<iframe src="[ORIGIN]" allow="[FEATURE] <'src' | [ORIGIN(s)]"></iframe>
例如:
<iframe src="https://trusted-site.example" allow="geolocation">
處理 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 開發人員工具。
- 開啟「應用程式」面板查看每個頁框許可和禁止的功能。
- 在側欄中,選取要檢查的頁框。系統會列出所選影格可使用的功能,以及該影格中封鎖的功能清單。
從功能政策遷移
如果您目前正在使用 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」端點,接收在該影格內發生任何違規情況的報告(如上方範例所示)子頁框必須自行設定報表設定。
瞭解詳情
如要進一步瞭解權限政策,請參閱下列資源: