Permissions-Policy ヘッダー

構文

# 単一のディレクティブ
Permissions-Policy: <directive>=<allowlist>

# レポートエンドポイント付きの単一のディレクティブ
Permissions-Policy: <directive>=<allowlist>;report-to=<endpoint>

# 複数のディレクティブ、サーバーレポートエンドポイント有りと無し
Permissions-Policy: <directive>=<allowlist>, <directive>=<allowlist>;report-to=<endpoint>, ...

このヘッダーを使用することで、1 つ以上のディレクティブの許可リストを設定できます。また、オプションで、ポリシー違反のレポートを送信するサーバーのエンドポイントを示す、ディレクティブごとの report-to パラメーターを設定することも可能です。 それぞれのディレクティブの項目はカンマ区切りで指定します。

<directive>

allowlist に適用される権限ポリシーディレクティブです。許可されているディレクティブ名の一覧は、以下のディレクティブを参照してください。

<allowlist>

許可リストとは、括弧内に次の値が空白で区切られて 1 つ以上含まれているオリジンのリストです。

* （ワイルドカード）

この機能は、この文書と、含まれるすべての閲覧コンテキスト (<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> の allow 属性には引き継がれないことに注意してください。

* の値 (すべてのオリジンで有効) または () (すべてのオリジンで無効) は単独でのみ使用できますが、 self と src は一つ以上のオリジンと一緒に使用することができます。

メモ: ディレクティブにはデフォルトの許可リストがあり、 Permissions-Policy HTTP ヘッダーでは常に *、self、none のいずれかになります。これらは個々のディレクティブのリファレンスページで指定されています。 <iframe> の allow 属性では、デフォルトの動作は常に src です。

report-to=<endpoint> 省略可

report-to 引数を使用すると、関連付けられたディレクティブのポリシー違反が発生した場合にレポートが送信されるレポート送信先エンドポイントの名前を示すことができます。 エンドポイント名とその関連付けられた URL は、別個の HTTP Reporting-Endpoints レスポンスヘッダーで指定しなければなりません。

省略された場合、レポートは、定義されている場合は default レポートエンドポイント に送信されます。 詳細については、レポート API をご覧ください。

対応している場合、その権限ポリシーのオリジンにワイルドカードを含めることができます。 これには、許可リストに複数の異なるサブドメインを明示的に指定する代わりに、ワイルドカードを使用して単一のオリジンですべてのサブドメインを指定するという意味があります。

そのため以下のような指定は

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

このように書き換えることができます。

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

ディレクティブ

accelerometer

現在の文書が、端末の加速度に関する情報を、 Accelerometer インターフェイスを通じて収集することを許可するかどうかを制御します。

ambient-light-sensor

現在の文書が、端末の周囲の環境における光量についての情報を、 AmbientLightSensor インターフェイスを通じて収集することを許可するかどうかを制御します。

aria-notify

現在の文書が、ariaNotify() メソッドを使用してスクリーンリーダーへの通知を発生することができるかどうかを制御します。

attribution-reporting

現在の文書が帰属レポート API を使用することを許可するかどうかを制御します。

autoplay

現在の文書で HTMLMediaElement インターフェイスがメディアの自動再生をリクエストすることを無効にするかどうかを制御します。このポリシーが無効であり、ユーザーによる操作がなかった場合、 HTMLMediaElement.play() が返すプロミス (Promise) が DOMException で拒否されます。 <audio> および <video> 要素の autoplay 属性は無視されます。

bluetooth

Web Bluetooth API の使用を許可するかどうかを制御します。このポリシーが無効になっている場合、 Navigator.bluetooth が返す Bluetooth オブジェクトのメソッドは false を返すか、または返されたプロミス (Promise) を SecurityError の DOMException で拒否します。

browsing-topics

トピック API へのアクセスを制御します。ポリシーでトピック API の使用が明確に禁止されている場合、 Document.browsingTopics() メソッドを呼び出そうとしたり、 Sec-Browsing-Topics ヘッダー付きのリクエストを送信しようとしても、 NotAllowedError の DOMException で失敗します。

camera

現在の文書が動画入力機器を使用することを許可するかどうかを制御します。 このポリシーが無効であれば、 getUserMedia() が返すプロミス (Promise) は NotAllowedError の DOMException で拒否されます。

captured-surface-control

このプロパティは、文書が Captured Surface Control API を使用できるかどうかを制御します。 その権限がない場合、API の主要なメソッドによって返されるプロミスは、NotAllowedError DOMException を理由に拒否されます。

ch-ua-high-entropy-values

この設定は、文書が NavigatorUAData.getHighEntropyValues() メソッドを使用して、高エントロピーのユーザーエージェントデータを取得することができるかどうかを制御します。 その権限が許可されていない場合、このメソッドは brands、mobile、platform の低エントロピーデータのみを返します。

compute-pressure

圧力計算 API へのアクセスを制御します。

cross-origin-isolated

現在の文書がオリジン間分離として扱うことができるかどうかを制御します。

deferred-fetch

最上位ドメインの fetchLater() クオータの割り当てを制御します。

deferred-fetch-minimal

オリジン間で共有されるサブフレームの fetchLater() クオータの割り当てを制御します。

display-capture

現在の文書が getDisplayMedia() メソッドを使用して画面の内容をキャプチャすることを許可するかどうかを制御します。このポリシーが無効であれば、表示内容をキャプチャする許可がない場合、 getDisplayMedia() から返却されるプロミスが NotAllowedError で拒否されます。

encrypted-media

現在の文書が Encrypted Media Extensions API (EME) を使用することを許可するかどうかを制御します。このポリシーが無効であれば、 Navigator.requestMediaKeySystemAccess() から返却されたプロミス (Promise) が DOMException で拒否されます。

fullscreen

現在の文書が Element.requestFullscreen() を使用することを許可するかどうかを制御します。このポリシーが無効であれば、返却されたプロミス (Promise) が TypeError で拒否されます。

gamepad

現在の文書が Gamepad API を使用することを許可するかどうかを制御します。 このポリシーが無効であれば、 Navigator.getGamepads() の呼び出しで SecurityError の DOMException が発生するようになり、 gamepadconnected および gamepaddisconnected イベントは発生しなくなります。

geolocation

現在の文書が Geolocation インターフェイスを使用することを許可するかどうかを制御します。このポリシーが無効であれば、 getCurrentPosition() および watchPosition() を呼び出すと、関数のコールバックが呼び出され、 PositionError コードが PERMISSION_DENIED になります。

gyroscope

現在の文書が Gyroscope インターフェイスを通じて、端末の方向に関する情報を収集することを許可するかどうかを制御します。

hid

現在の文書が WebHID API を使用して、代替キーボードやゲームパッドなどの一般的ではない、または特殊なヒューマンインターフェイス端末に接続することを許可するかどうかを制御します。

identity-credentials-get

現在の文書が連合資格情報管理 API (FedCM) の使用を許可されているかどうかを制御します。

idle-detection

現在の文書が、ユーザーが端末と通信していることを検出するアイドル検出 API が利用可能かどうかを制御します。例えば、チャットアプリケーションで「在席中」/「離席中」の状態を報告する場合などです。

language-detector

Translator and Language Detector API の言語検出機能へのアクセスを制御します。

local-fonts

現在の文書が、 Window.queryLocalFonts() メソッド（ローカルフォントアクセス API も参照）を介して、ユーザーのローカルにインストールされたフォントに関するデータを収集することを許可するかどうかを制御します。

magnetometer

現在の文書が Magnetometer インターフェイスを通じて、端末の方向に関する情報を収集することを許可するかどうかを制御します。

microphone

現在の文書がオーディオ入力機器を使用することを許可するかどうかを制御します。このポリシーが無効であれば、 MediaDevices.getUserMedia() で返却されたプロミス (Promise) が NotAllowedError の DOMException で拒否されます。

midi

現在の文書が Web MIDI API を使用することを許可するかどうかを制御します。このポリシーが無効であれば、 Navigator.requestMIDIAccess() から返却されたプロミス (Promise) が DOMException で拒否されます。

on-device-speech-recognition

ウェブ音声 API の端末内音声認識機能へのアクセスを制御します。

otp-credentials

現在の文書が、 WebOTP API を使用して、アプリのサーバーから送信された特別に書式化された SMS メッセージからワンタイムパスワード (OTP) をリクエストすること、すなわち navigator.credentials.get({otp: ..., ...}) を許可するかどうかを制御します。

payment

現在の文書が決済リクエスト API を使用することを許可するかどうかを制御します。このポリシーが有効であれば、 PaymentRequest() コンストラクターで SecurityError の DOMException が発生します。

picture-in-picture

現在の文書が、該当する API を使用してピクチャインピクチャモードで動画を再生することを許可するかどうかを制御します。

private-state-token-issuance

プライベートステートトークン に対する token-request 操作の使用を制御します。

private-state-token-redemption

プライベートステートトークン の token-redemption および send-redemption-record 操作の使用を制御します。

publickey-credentials-create

現在の文書がウェブ認証 API を使用して、新しい非対称キー資格情報を作成すること、すなわち navigator.credentials.create({publicKey: ..., ...}) を許可するかどうかを制御します。

publickey-credentials-get

現在の文書がウェブ認証 API を使用して、すでに保存されている公開鍵資格情報を再取得すること、すなわち navigator.credentials.get({publicKey: ..., ...}) を許可するかどうかを制御します 。

screen-wake-lock

現在の文書が画面起動ロック API を使用して、端末が画面をオフにしたり暗くしたりしてはいけないことを示すことを許可するかどうかを制御します。

serial

現在の文書が、ウェブシリアル API を使用して、シリアルポートに直接接続されたシリアル機器、またはシリアルポートをエミュレートする USB または Bluetooth 機器と通信することを許可するかどうかを制御します。

speaker-selection

現在の文書がオーディオ出力機器 API を使用して、スピーカーを列挙したり選択したりすることを許可するかどうかを制御します。

storage-access

サードパーティのコンテキスト（すなわち、 <iframe> に埋め込まれた）で読み込まれた文書内のストレージアクセス API を使用して、分離されていないクッキーにアクセスすることを許可するかどうかを制御します。

translator

翻訳および言語検出 API の翻訳機能へのアクセスを制御します。

summarizer

要約 API へのアクセスを制御します。

usb

現在の文書が WebUSB API を使用することを許可するかどうかを制御します。

web-share

現在の文書が Web Share API の Navigator.share() を使用して、テキスト、リンク、画像、その他のコンテンツをモバイルアプリなどのユーザーが任意に選択した任意の場所に共有することを許可するかどうかを制御します。

window-management

現在の文書が、ウィンドウ管理 API を使用して複数のディスプレイ上のウィンドウを管理することを許可するかどうかを制御します。

xr-spatial-tracking

現在の文書が WebXR Device 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 値について特に言及する価値があります。上記で述べたように、この許可リスト値を使用すると、 src 属性の URL と同じオリジンから読み込まれた文書である限り、関連付けられた機能がこの <iframe> で許可されることになります。この値は、 allow に列挙された機能のデフォルトの allowlist 値であるため、次のものは同等です。

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

強力な機能へのアクセスを拒否する

SecureCorp Inc. が、アプリケーションでマイクと位置情報 API を無効にしたがっているとします。以下の権限ポリシーを設定する HTTP レスポンスヘッダーを配信することで実現できます。

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

オリジンのリストに () キーワードを指定すると、指定された機能がオリジンに関係なく、すべての閲覧コンテキスト (すべての <iframe> を含む) で無効になります。

HTTP ヘッダーと <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>

違反のレポート

この例では、Permissions-Policy の違反をサーバーのエンドポイントに報告するように設定する方法を示します。

下記のレスポンスヘッダーは位置情報の取得をブロックし、この機能のレポート用エンドポイント名を "geo_endpoint" として定義します。 HTTP Reporting-Endpoints レスポンスヘッダーは、このエンドポイント名の URL を定義するために使用されます。

Reporting-Endpoints: geo_endpoint="https://example.com/reports"
Permissions-Policy: geolocation=();report-to=geo_endpoint

Reporting-Endpoints: default="https://example.com/reports"
Permissions-Policy: geolocation=()

ページがブロックされた機能を使用しようとすると、違反が発生します。例を示します。

navigator.geolocation.getCurrentPosition(
  () => {},
  () => {},
);

エンドポイントに送信されるレポート本体は、次のような形式になります。

[
  {
    "age": 48512,
    "body": {
      "columnNumber": 29,
      "disposition": "enforce",
      "lineNumber": 44,
      "message": "Permissions policy violation: geolocation access has been blocked because of a permissions policy applied to the current document.",
      "featureId": "geolocation",
      "sourceFile": "https://example.com/"
    },
    "type": "permissions-policy-violation",
    "url": "https://example.com/",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36"
  }
]

仕様書

ブラウザーの互換性

関連情報

• 権限ポリシー
• Document.featurePolicy および FeaturePolicy
• Content-Security-Policy
• Referrer-Policy
• Reporting-Endpoints
• PermissionsPolicyViolationReport
• ReportingObserver
• レポート API