Permissions-Policy

使い方

Permissions-Policy レスポンスヘッダーは、現在のフレームで許可されるブラウザ機能を制限します。各ポリシーは、機能のディレクティブと、その機能にアクセスできるオリジンを定義する許可リストを組み合わせます。

Permissions-Policy: <directive>=<allowlist>

注意

推奨される出発点となるポリシーは、サイトが使わない機能を無効化することです。Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=(), bluetooth=() のようにします。セキュリティスキャナーは Permissions-Policy ヘッダーの欠落を指摘します。最小限のポリシーを設定すれば、サイトの機能に影響を与えることなくこの指摘を解消できます。

注意

Permissions-Policy の仕組みは、以前は Feature Policy として知られていました。

ディレクティブ

ディレクティブ名は、制御の対象となるブラウザ機能を識別します。標準化されたディレクティブの一部を挙げます。

注意

interest-cohort ディレクティブは Federated Learning of Cohorts（FLoC）をブロックするために使われていました。Google は 2022 年に FLoC を断念し、この API を Topics API に置き換えました。interest-cohort ディレクティブはブラウザの実装から削除されています。

許可リストの値

allowlist は、どのオリジンがその機能を使えるかを制御します。

注意

unload ディレクティブは、そのオリジンにおける unload イベントハンドラーをブロックします。Permissions-Policy: unload=() を設定すると、ファーストパーティのコード、サードパーティのスクリプト、ブラウザ拡張機能が unload ハンドラーを登録できなくなります。unload ハンドラーがあるとブラウザは戻る・進むの即時ナビゲーションのためにページをキャッシュできないため、これは back-forward cache（bfcache）の性能にとって重要です。Chrome は、トラフィックの多いサイトから始めて全サイトへと広げながら、unload イベントを段階的に完全に非推奨化しつつあります。unload=() を設定すれば直ちにこの非推奨化を選択したことになり、展開スケジュールに関わらず bfcache の適用対象であることが保証されます。

例

次の例では、サーバーが geolocation 機能をすべてのコンテキストで無効にすることを示しています。

Permissions-Policy: geolocation=()

次の例では、サーバーが encrypted-media 機能を report.example.re を除くすべてのオリジンで無効にすることを示しています。

Permissions-Policy: encrypted-media=("https://report.example.re")

次の例では、サーバーが microphone 機能を、自身と example.re のオリジンを除くすべてのオリジンで無効にすることを示しています。

Permissions-Policy: microphone=(self "https://example.re")

bfcache の適用対象となりやすくするために unload ハンドラーをブロックします。これにより、サードパーティのスクリプトや拡張機能が unload イベントを登録して戻る・進むのナビゲーション性能を低下させるのを防げます。

Permissions-Policy: unload=()

トラブルシューティング

Permissions-Policy の違反はほとんどの場合、目に見えるブラウザのプロンプトを伴わず、ブロックされた機能が拒否状態を返すかエラーを投げる形で静かに現れます。

allow 属性がないために iframe 内で機能がブロックされる。親ページがある機能を許可していても、埋め込まれた iframe がその機能にアクセスするには明示的な allow 属性が必要です。iframe タグに属性を追加してください。

ポリシーを設定した後に geolocation、camera、microphone が動かない。Permissions-Policy: geolocation=() のようなポリシーは、ページ自身を含むすべてのオリジンでその機能を無効にします。同一オリジンでのみ機能を許可するには geolocation=(self) を使います。特定の埋め込みオリジンも許可するには geolocation=(self “https://maps.example.re”) を使います。ポリシーがすでに拒否した機能について、ブラウザがユーザーに確認を求めることはありません。

ワイルドカード * がすべての機能で機能するわけではない。一部の機能は * という許可リストの値をサポートしておらず、明示的なオリジンのリストに限定されます。* が効かない場合は、許可する各オリジンを個別に指定してください。認識されない、あるいはサポートされない許可リストの値に関する警告がないか、ブラウザのコンソールを確認します。

Feature-Policy から Permissions-Policy への移行。従来の Feature-Policy ヘッダーは異なる構文を使います。Feature-Policy: geolocation ‘self’ に対して Permissions-Policy: geolocation=(self) となります。両方のヘッダーが存在する場合、Permissions-Policy をサポートするブラウザは Feature-Policy を無視します。ヘッダー名を更新し、構文を変換してください。スペースを = に置き換え、オリジンのリストを括弧で囲み、self と none の周りの単一引用符を外します（‘none’ の代わりに () を使います）。

document.featurePolicy.allowsFeature() でデバッグする。Chromium ベースのブラウザでは、DevTools の Console を開いて document.featurePolicy.allowsFeature(‘camera’) を実行すると、現在のコンテキストでその機能が許可されているかを確認できます。これは true または false を返します。iframe のコンテキストについては、第 2 引数にオリジンを渡します。document.featurePolicy.allowsFeature(‘camera’, ‘https://embed.example.re’) のようにします。Firefox は document.featurePolicy の代わりに document.permissionsPolicy を使います。