ページとページ上のサードパーティの iframe がブラウザ機能にアクセスできるようにする方法を管理します。
権限ポリシー（旧称「機能ポリシー」）では、デベロッパーが ページで使用できるブラウザ機能、その iframe、 ブラウザに適用する一連のポリシーを宣言することで、サブリソースにアクセスできます。これらの ポリシーは、レスポンス ヘッダーの送信元リストで指定された送信元に適用されます。 オリジンリストには同一オリジンやクロスオリジンを含めることができ、 ブラウザ機能へのファーストパーティとサードパーティのアクセスを制御する。
ユーザーは、より強力な機能へのアクセスを許可することを最終的な決定を下し、プロンプトを通じて明示的な権限を付与する必要があります。
権限ポリシーにより、トップレベル サイトは自身のサイトと 3 つ目のサイト 判断するユーザーの負担を軽減し、 正当なものかどうかを判定します。たとえば、 権限ポリシーを通じてすべてのサードパーティに対して位置情報機能をブロックする 開発者は、第三者がユーザーの認証情報にアクセスできないように 役立ちます
権限に関するポリシーの変更
権限ポリシーは、以前は機能ポリシーという名称でした。主なコンセプトは同じですが、名称とともに重要な変更がいくつかあります。
構造化フィールドの使用方法
構造化フィールドは、HTTP ヘッダー フィールド値の解析とシリアル化を標準化するための一般的なデータ構造のセットを提供します。構造化フィールドについて詳しくは、Fastly のブログ投稿「構造化ヘッダー フィールドによる HTTP の改善」をご覧ください。
geolocation 'self' https://example.com; camera 'none'
機能ポリシーで変更前
geolocation=(self "https://example.com"), camera=()
権限ポリシーが追加されました。
ヘッダーを iframe の allow 属性と組み合わせる
機能ポリシーでは、ヘッダーのオリジン リストにオリジンを追加するか、iframe タグに allow 属性を追加することで、クロスオリジン フレームに対象物を追加できます。権限ポリシーでは、オリジンリストにクロスオリジン フレームを追加する場合、そのオリジンの iframe タグに allow 属性を含める必要があります。
レスポンスに Permissions Policy ヘッダーが含まれていない場合、配信元リストのデフォルト値は * とみなされます。allow 属性を iframe に追加すると、この機能にアクセスできるようになります。
そのため、オリジン リストに記載されていないクロスオリジンの iframe は、allow が存在する場合でもこの機能へのアクセスをブロックするように、デベロッパーがレスポンスに Permissions Policy ヘッダーを明示的に設定することをおすすめします。
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")
信頼できるサイトの iframe タグに allow 属性を明示的に設定します。
<iframe src="https://trusted-site.example" allow="geolocation">
この例では、ヘッダー送信元リストにより、サイト（self）と trusted-site.example のみが位置情報機能を使用できます。ad.example では位置情報を使用できません。
- サイト
your-site.exampleは、ユーザーの同意を得た位置情報機能の使用が許可されています。 - 同一オリジンの iframe（
your-site.example）では、allow属性を使用しなくてもこの機能を使用できます。 - オリジン リストに追加されていない別のサブドメイン（
subdomain.your-site-example）から配信される iframe で、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 属性を含める必要があります。
Key-Value ペアの例を次に示します。
- 構文:
[FEATURE]=*<ph type="x-smartling-placeholder">- </ph>
- すべてのオリジンに適用されるポリシー
- 例:
geolocation=*
- 構文:
[FEATURE]=(self)<ph type="x-smartling-placeholder">- </ph>
- 同一オリジンにポリシーを適用
- 例:
geolocation=(self)
- 構文:
[FEATURE]=(self [ORIGIN(s)])<ph type="x-smartling-placeholder">- </ph>
- 同じオリジンと指定したオリジンにポリシーが適用されます
- 例:
geolocation=(self "https://a.example" "https://b.example") selfはhttps://your-site.exampleの省略形です。
- 構文:
[FEATURE]=([ORIGIN(s)])<ph type="x-smartling-placeholder">- </ph>
- 同じオリジンと指定したオリジンにポリシーが適用されます
- 例:
geolocation=("https://your-site.example" "https://a.example" "https://b.example") - この構文を使用する場合、オリジンの一つを埋め込みのオリジンにする必要があります。埋め込みページ自体に権限が付与されていない場合、そのページに埋め込まれた iframe は、配信元リストに追加されていてもブロックされます。これは、権限ポリシーによって権限が委任されるためです。
selfトークンを使用することもできます。
- 構文:
[FEATURE]=()<ph type="x-smartling-placeholder">- </ph>
- この機能はすべてのオリジンでブロックされています
- 例:
geolocation=()
異なるサブドメインとパス
異なるサブドメイン（https://your-site.example や https://subdomain.your-site.example など）は、「同一サイトだがクロスオリジン」と見なされます。そのため、配信元リストにサブドメインを追加しても、同じサイトの別のサブドメインへのアクセスは許可されません。この機能を使用するすべての埋め込みサブドメインを、オリジン リストに個別に追加する必要があります。たとえば、ユーザーのブラウジング トピックへのアクセスが、ヘッダー Permissions-Policy: browsing-topics=(self) でのみ同一オリジンに許可されている場合、同じサイト（https://subdomain.your-site.example）の別のサブドメインの iframe はトピックにアクセスできません。
異なるパス（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 の移動先のオリジンに適用されません。iframe の移動先オリジンを allow 属性にリストすると、元の 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 は位置情報機能にアクセスできません。元のページと、iframe タグで allow 属性があり、オリジンリストにある https://trusted-site.example のみがユーザーの機能にアクセスできます。
この設定については、デモをご覧ください。
機能はすべてのオリジンでブロックされています
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, オリジン)
- 指定されたオリジンで対象物が許可されている場合は
trueを返します。 documentでこのメソッドが呼び出された場合、このメソッドは、Feature Policy と同様に、指定されたオリジンで機能が許可されているかどうかを通知しなくなります。このメソッドは、そのオリジンに対して対象物を許可できることを示しています。さらに、iframe にallow属性が設定されているかどうかを確認する必要があります。デベロッパーは iframe 要素のallow属性をさらにチェックして、この機能がサードパーティのオリジンに対して許可されているかどうかを判断する必要があります。
element オブジェクトを使用して iframe の機能を確認する
許可属性を考慮しない document.allowsFeature(feature, origin) とは異なり、allow 属性を考慮する element.allowsFeature(feature) を使用できます。
const someIframeEl = document.getElementById('some-iframe')
const isCameraFeatureAllowed = someIframeEl.featurePolicy.allowsFeature('camera')
featurePolicy.allowedFeatures()
- デフォルトのオリジンの使用が許可されている機能のリストを返します。
- 権限ポリシーと機能ポリシーで設定されたどちらのポリシーでも動作は同じ
- 関連付けられているノードが iframe の場合は、allow 属性が考慮されます。
featurePolicy.features()
- ブラウザで使用可能な機能のリストを返します。
- 権限ポリシーと機能ポリシーで設定されたどちらのポリシーでも動作は同じ
Chrome DevTools の統合
DevTools の権限ポリシーの仕組みを確認します。
- Chrome DevTools を開きます。
- [Application] パネルを開いて、各フレームで許可されている機能と許可されていない機能を確認します。
- サイドバーで、検査するフレームを選択します。選択したフレームで使用できる機能のリストと、そのフレームでブロックされている機能のリストが表示されます。
Feature-Policy からの移行
現在 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) は allow 属性に対応していますが、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
document を使用して既存のコードを更新する代わりに、前の例のように element オブジェクトで allowsFeature() を呼び出すことをおすすめします。
Reporting API
Reporting API はウェブ アプリケーション向けの一貫したレポート メカニズムを提供します。また、権限ポリシー違反の Reporting API は試験運用版機能としてご利用いただけます。
試験運用版の機能をテストする場合は、チュートリアルに沿って、chrome://flags/#enable-experimental-web-platform-features でフラグを有効にします。このフラグを有効にすると、DevTools の [Application] タブで、権限ポリシー違反を確認できます。
次の例は、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」という名前のエンドポイントを設定することで、そのフレーム内で発生した違反からポリシー違反レポートを受信できます。使用します。サブフレームには独自のレポート構成が必要です。
補足説明
権限ポリシーの詳細については、次のリソースをご覧ください。