Browserfunktionen mit der Berechtigungsrichtlinie steuern

Hier können Sie festlegen, wie Ihre Seite und Drittanbieter-Iframes auf Ihrer Seite auf Browserfunktionen zugreifen können.

Kevin K. Lee
Kevin K. Lee
X GitHub

Mit der Berechtigungsrichtlinie, früher als Funktionsrichtlinie bezeichnet, können Entwickler die Browserfunktionen steuern, die für eine Seite, ihre Iframes und untergeordneten Ressourcen verfügbar sind. Dazu deklarieren sie eine Reihe von Richtlinien, die vom Browser erzwungen werden. Diese Richtlinien werden auf Ursprünge angewendet, die in einer Ursprungsliste in Antwortheadern angegeben sind. Die Ursprungsliste kann Ursprungs- und/oder plattformübergreifende Elemente enthalten. So kann der Entwickler den Zugriff von selbst erhobenen Daten und Drittanbietern auf Browserfunktionen steuern.

Der Nutzer entscheidet selbst, ob er den Zugriff auf leistungsstärkere Funktionen zulassen möchte. Er muss eine explizite Berechtigung erteilen, indem er eine Aufforderung akzeptiert.

Mit der Berechtigungsrichtlinie kann die Website der obersten Ebene festlegen, was sie und ihre Drittanbieter verwenden möchten. So muss der Nutzer nicht mehr selbst entscheiden, ob die Anfrage auf Funktionszugriff legitim ist oder nicht. Wenn Entwickler beispielsweise die Berechtigungsrichtlinie verwenden, um die Standortermittlung für alle Drittanbieter zu blockieren, können sie sicher sein, dass kein Drittanbieter Zugriff auf die Standortermittlung des Nutzers erhält.

Änderungen an der Richtlinie zu Berechtigungen

Die Berechtigungsrichtlinie hieß früher „Funktionsrichtlinie“. Die wichtigsten Konzepte bleiben gleich, aber es gibt einige wichtige Änderungen neben dem Namen.

Verwendung strukturierter Felder

Strukturierte Felder bieten eine Reihe gängiger Datenstrukturen, um das Parsen und Serialisieren von HTTP-Header-Feldwerten zu standardisieren. Weitere Informationen zu strukturierten Feldern finden Sie im Blogpost „Improving HTTP with structured header fields“ (HTTP mit strukturierten Headerfeldern verbessern) von Fastly.

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

Vorher mit der Feature-Richtlinie

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

Jetzt mit Berechtigungsrichtlinien.

Header mit dem iFrame-Attribut allow kombinieren

Mit der Funktion „Funktionsrichtlinie“ können Sie die Funktion einem Frame mit unterschiedlichen Ursprüngen hinzufügen, indem Sie entweder den Ursprung der Liste der Header-Ursprünge hinzufügen oder dem iFrame-Tag das allow-Attribut hinzufügen. Wenn Sie der Ursprungsliste mit der Berechtigungsrichtlinie einen Frame mit mehreren Ursprüngen hinzufügen, muss das iframe-Tag für diesen Ursprung das Attribut allow enthalten. Wenn die Antwort keinen Permissions Policy-Header enthält, gilt für die Ursprungsliste der Standardwert *. Wenn du dem Iframe das Attribut allow hinzufügst, kannst du auf die Funktion zugreifen.

Wir empfehlen daher, den Header „Permissions Policy“ in der Antwort explizit festzulegen, damit iframes mit unterschiedlichen Ursprüngen, die nicht in der Ursprungsliste aufgeführt sind, den Zugriff auf diese Funktion blockiert wird, auch wenn allow vorhanden ist.

Die Richtlinie für Funktionen kann auch nach Chrome 88 verwendet werden, dient aber als Alias für die Berechtigungsrichtlinie. Abgesehen von der Syntax gibt es keinen Unterschied in der Logik. Wenn sowohl Header für die Berechtigungsrichtlinie als auch für die Funktionsrichtlinie verwendet werden, hat der Permissions-Policy-Header eine höhere Priorität und überschreibt den Wert, der im Feature-Policy-Header angegeben ist.

Wie verwende ich die Berechtigungsrichtlinie?

Kurzübersicht

Bevor wir uns näher damit befassen, sehen wir uns ein gängiges Szenario an: Sie sind Inhaber einer Website und möchten festlegen, wie Browserfunktionen von Ihrer Website und von Drittanbietercode verwendet werden.

  • Ihre Website lautet https://your-site.example.
  • Auf Ihrer Website ist ein iFrame von Same-Origin (https://your-site.example) eingebettet.
  • Ihre Website enthält einen vertrauenswürdigen iFrame von https://trusted-site.example.
  • Auf Ihrer Website werden auch Anzeigen ausgeliefert, die von https://ad.example ausgeliefert werden.
  • Sie möchten die Standortbestimmung nur für Ihre Website und die vertrauenswürdige Website zulassen, nicht für die Anzeige.

Verwenden Sie in diesem Fall den folgenden Header:

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

Legen Sie das allow-Attribut für das iFrame-Tag der vertrauenswürdigen Website explizit fest:

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

Kurzübersicht zur Verwendung der Berechtigungsrichtlinie

In diesem Beispiel kann die Funktion „Standortermittlung“ in der Liste der Header-Herkunft nur von Ihrer Website (self) und trusted-site.example verwendet werden. ad.example darf die Standortbestimmung nicht verwenden.

  1. Ihre Website your-site.example darf die Standortermittlung mit der Einwilligung des Nutzers verwenden.
  2. In einem IFRAME mit gleicher Quelle (your-site.example) darf die Funktion ohne das allow-Attribut verwendet werden.
  3. Ein iFrame, der von einer anderen Subdomain (subdomain.your-site-example) ausgeliefert wird, die nicht der Ursprungsliste hinzugefügt wurde, und für den das Attribut „allow“ im iFrame-Tag festgelegt ist, kann die Funktion nicht verwenden. Unterschiedliche Subdomains gelten als Website-intern, aber plattformübergreifend.
  4. Für einen plattformübergreifenden IFrame (trusted-site.example), der der Ursprungsliste hinzugefügt wurde und für den das allow-Attribut auf dem IFrame-Tag festgelegt ist, darf die Funktion verwendet werden.
  5. Ein trusted-site.example-Iframe, der der Ursprungsliste ohne das allow-Attribut hinzugefügt wurde, kann die Funktion nicht verwenden.
  6. Für einen plattformübergreifenden iFrame (ad.example), der nicht der Ursprungsliste hinzugefügt wurde, ist die Verwendung der Funktion nicht zulässig, auch wenn das allow-Attribut im iFrame-Tag enthalten ist.

Permissions-Policy-HTTP-Antwortheader

Der Nutzer sendet eine Anfrage, der Server antwortet mit dem Header „Permissions Policy“ (Berechtigungsrichtlinie) und der Browser gewährt dann basierend auf diesem Header Zugriff.

Permissions-Policy: <feature>=(<token>|<origin(s)>)

Verwenden Sie in der Antwort vom Server einen Permissions-Policy-Header, um die zulässigen Ursprünge für eine Funktion festzulegen. Der Headerwert kann eine Kombination aus Tokens und Strings von Ursprüngen enthalten. Die verfügbaren Tokens sind * für alle Ursprünge und self für denselben Ursprung.

Wenn der Titel mehrere Funktionen umfasst, trennen Sie diese durch ein Komma. Wenn Sie mehrere Ursprünge angeben, trennen Sie diese in der Ursprungsliste durch ein Leerzeichen. Header, die einen Ursprung für eine Cross-Origin-Anfrage enthalten, müssen das allow-Attribut im Iframe-Tag enthalten.

Hier einige Beispiele für Schlüssel/Wert-Paare:

  • Syntax: [FEATURE]=*
    • Richtlinie, die auf alle Ursprünge angewendet wird
    • Beispiel: geolocation=*
  • Syntax: [FEATURE]=(self)
    • Richtlinie auf „Same-Origin“ angewendet
    • Beispiel: geolocation=(self)
  • Syntax: [FEATURE]=(self [ORIGIN(s)])
    • Richtlinie wird auf denselben Ursprung und die angegebenen Ursprünge angewendet
    • Beispiel: geolocation=(self "https://a.example" "https://b.example")
    • self ist eine Abkürzung für https://your-site.example.
  • Syntax: [FEATURE]=([ORIGIN(s)])
    • Richtlinie wird auf denselben Ursprung und die angegebenen Ursprünge angewendet
    • Beispiel: geolocation=("https://your-site.example" "https://a.example" "https://b.example")
    • Bei Verwendung dieser Syntax sollte einer der Ursprünge der Ursprung des Embedders sein. Wenn der Seite des Einbettungsanbieters selbst keine Berechtigungen gewährt werden, werden auch die darin eingebetteten Iframes blockiert, auch wenn sie der Ursprungsliste hinzugefügt werden, da die Berechtigungsrichtlinie Berechtigungen delegiert. Sie können auch das self-Token verwenden.
  • Syntax: [FEATURE]=()
    • Funktion für alle Ursprünge blockiert
    • Beispiel: geolocation=()

Unterschiedliche Subdomains und Pfade

Unterschiedliche Subdomains wie https://your-site.example und https://subdomain.your-site.example werden als Websites mit demselben Ursprung, aber unterschiedlichen Ursprüngen betrachtet. Wenn Sie also eine Subdomain in die Ursprungsliste aufnehmen, erhalten Sie keinen Zugriff auf eine andere Subdomain derselben Website. Jede eingebettete Subdomain, für die die Funktion verwendet werden soll, muss der Ursprungsliste einzeln hinzugefügt werden. Wenn beispielsweise der Zugriff auf die Themen der Websitenutzung des Nutzers nur mit dem Header Permissions-Policy: browsing-topics=(self) für denselben Ursprung zulässig ist, hat ein Iframe von einer anderen Subdomain derselben Website, https://subdomain.your-site.example, keinen Zugriff auf die Themen.

Unterschiedliche Pfade wie https://your-site.example und https://your-site.example/embed gelten als Pfade mit demselben Ursprung und müssen nicht in der Ursprungsliste aufgeführt werden.

iFrame-Attribut allow

iFrame-Einrichtung

Für die plattformübergreifende Nutzung benötigt ein Iframe das allow-Attribut im Tag, um auf die Funktion zuzugreifen.

Syntax: <iframe src="[ORIGIN]" allow="[FEATURE] <'src' | [ORIGIN(s)]"></iframe>

Beispiel:

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

iFrame-Navigation verarbeiten

iFrame-Navigation einrichten

Wenn ein Iframe zu einer anderen Quelle weiterleitet, wird die Richtlinie standardmäßig nicht auf die Quelle angewendet, zu der der Iframe weiterleitet. Wenn Sie den Ursprung, zu dem der Iframe weitergeleitet wird, im Attribut allow angeben, wird die Berechtigungsrichtlinie, die auf den ursprünglichen Iframe angewendet wurde, auf den Ursprung angewendet, zu dem der Iframe weitergeleitet wird.

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

In der Demo für die Navigation in iFrames können Sie sich das ansehen.

Beispielkonfigurationen für Berechtigungsrichtlinien

Die Beispiele für die folgenden Konfigurationen finden Sie in der Demo.

Funktion für alle Ursprünge zulässig

Architektur aller Ursprünge, die auf die Funktion zugreifen dürfen

Permissions-Policy: geolocation=*

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

Wenn die Ursprungsliste auf das *-Token festgelegt ist, ist die Funktion für alle Ursprünge auf der Seite zulässig, einschließlich der Seite selbst und aller Iframes. In diesem Beispiel haben alle Codes, die von https://your-site.example und den iframes https://trusted-site.example und https://ad.example ausgeliefert werden, Zugriff auf die Geolokalisierungsfunktion im Browser des Nutzers. Das Attribut „allow“ muss auch für den Iframe selbst festgelegt werden. Außerdem muss der Ursprung der Header-Ursprungsliste hinzugefügt werden.

Diese Konfiguration ist in der Demo zu sehen.

Funktion nur für denselben Ursprung zulässig

Architektur, bei der nur derselbe Ursprung auf die Funktion zugreifen darf

Permissions-Policy: geolocation=(self)

Mit dem self-Token ist die Standortbestimmung nur für denselben Ursprung zulässig. Nutzer mit mehreren Ursprüngen haben keinen Zugriff auf die Funktion. In diesem Beispiel hat nur https://trusted-site.example (self) Zugriff auf die Standortbestimmung. Verwenden Sie diese Syntax, wenn die Funktion nur für Ihre Seite und nicht für andere Seiten gelten soll.

Diese Konfiguration ist in der Demo zu sehen.

Funktion für Same-Origin- und bestimmte Cross-Origin-Quellen zulässig

Architektur der angegebenen Ursprünge, die auf die Funktion zugreifen dürfen

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

Mit dieser Syntax kann die Standortermittlung sowohl für „self“ (https://your-site.example) als auch für https://trusted-site.example verwendet werden. Denken Sie daran, dem iFrame-Tag das Attribut „allow“ hinzuzufügen. Wenn es einen anderen IFrame mit <iframe src="https://ad.example" allow="geolocation"> gibt, hat https://ad.example keinen Zugriff auf die Geolokalisierungsfunktion. Nur die ursprüngliche Seite und https://trusted-site.example, die in der Ursprungsliste aufgeführt sind und das Attribut „allow“ im Iframe-Tag haben, haben Zugriff auf die Funktion des Nutzers.

Diese Konfiguration ist in der Demo zu sehen.

Funktion für alle Ursprünge blockiert

Architektur aller Ursprünge, die vom Zugriff auf die Funktion ausgeschlossen sind

Permissions-Policy: geolocation=()

Wenn die Quellenliste leer ist, wird die Funktion für alle Ursprünge blockiert. Diese Konfiguration ist in der Demo zu sehen.

JavaScript API verwenden

Die vorhandene JavaScript API der Funktionsweise der Richtlinie wird entweder als Objekt im Dokument oder im Element (document.featurePolicy or element.featurePolicy) gefunden. Die JavaScript API für die Berechtigungsrichtlinie wurde noch nicht implementiert.

Die Feature Policy API kann mit einigen Einschränkungen für Richtlinien verwendet werden, die durch die Berechtigungsrichtlinie festgelegt wurden. Es gibt noch offene Fragen zur Implementierung einer JavaScript API. Es wurde ein Vorschlag gemacht, die Logik in die Berechtigungs API zu verschieben. Wenn du etwas dazu sagen möchtest, kannst du dich an der Diskussion beteiligen.

featurePolicy.allowsFeature(feature)

  • Gibt true zurück, wenn die Funktion für die Standard-Herkunft zulässig ist.
  • Das Verhalten ist für beide Richtlinien identisch, die über die Berechtigungsrichtlinie und die vorherige Funktionsrichtlinie festgelegt werden.
  • Wenn allowsFeature() für ein iframe-Element (iframeEl.featurePolicy.allowsFeature('geolocation')) aufgerufen wird, gibt der zurückgegebene Wert an, ob das Attribut „allow“ für den iframe festgelegt ist.

featurePolicy.allowsFeature(feature, origin)

  • Gibt true zurück, wenn die Funktion für die angegebene Quelle zulässig ist.
  • Wenn die Methode auf document aufgerufen wird, gibt sie nicht mehr an, ob die Funktion für den angegebenen Ursprung zulässig ist, wie es bei der Funktion „Feature Policy“ der Fall war. Diese Methode gibt an, dass die Funktion für diesen Ursprung möglicherweise zulässig ist. Sie müssen zusätzlich prüfen, ob das Attribut allow für den Iframe festgelegt ist. Der Entwickler muss das allow-Attribut im iframe-Element zusätzlich prüfen, um festzustellen, ob die Funktion für den Drittanbieter-Ursprung zulässig ist.

In einem Iframe mit dem element-Objekt nach Funktionen suchen

Sie können element.allowsFeature(feature) verwenden, bei dem das Attribut „allow“ berücksichtigt wird, im Gegensatz zu document.allowsFeature(feature, origin), bei dem dies nicht der Fall ist.

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

featurePolicy.allowedFeatures()

  • Gibt eine Liste der Funktionen zurück, die für die Verwendung des Standard-Ursprungs zulässig sind.
  • Das Verhalten ist für beide Richtlinien identisch, die über die Berechtigungsrichtlinie und die Funktionsrichtlinie festgelegt werden.
  • Wenn der zugehörige Knoten ein Iframe ist, wird das Attribut „allow“ berücksichtigt.

featurePolicy.features()

  • Gibt eine Liste der im Browser verfügbaren Funktionen zurück.
  • Das Verhalten ist für beide Richtlinien identisch, die über die Berechtigungsrichtlinie und die Funktionsrichtlinie festgelegt werden.

Chrome-Entwicklertools-Integration

Einbindung der Chrome-Entwicklertools in die Berechtigungsrichtlinie

Hier erfahren Sie, wie die Berechtigungsrichtlinie in den DevTools funktioniert.

  1. Öffnen Sie die Chrome-Entwicklertools.
  2. Öffnen Sie den Bereich Anwendung, um die zulässigen und nicht zulässigen Funktionen der einzelnen Frames zu prüfen.
  3. Wählen Sie in der Seitenleiste den Frame aus, den Sie prüfen möchten. Sie sehen eine Liste der Funktionen, die im ausgewählten Frame verwendet werden dürfen, und eine Liste der Funktionen, die in diesem Frame blockiert sind.

Migration von der Feature-Richtlinie

Wenn Sie die Feature-Policy-Überschrift verwenden, können Sie die folgenden Schritte ausführen, um zur Berechtigungsrichtlinie zu migrieren.

Header der Richtlinien zu Funktionen durch Header der Berechtigungsrichtlinien ersetzen

Da die Überschriften der Funktionsrichtlinien nur in Chromium-basierten Browsern und die Überschriften der Berechtigungsrichtlinien seit Chrome 88 unterstützt werden, können Sie die vorhandenen Überschriften mit der Berechtigungsrichtlinie aktualisieren.

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

Vorher mit der Feature-Richtlinie

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

Jetzt mit Berechtigungsrichtlinien.

Nutzung von document.allowsFeature(feature, origin) aktualisieren

Wenn Sie die document.allowsFeature(feature, origin)-Methode verwenden, um zulässige Funktionen für iFrames zu prüfen, verwenden Sie die allowsFeature(feature)-Methode, die an das iFrame-Element angehängt ist, und nicht die enthaltene document. Bei der Methode element.allowsFeature(feature) wird das Attribut „allow“ berücksichtigt, bei document.allowsFeature(feature, origin) hingegen nicht.

Funktionszugriff mit document prüfen

Wenn Sie document weiterhin als Basisknoten verwenden möchten, müssen Sie im iFrame-Tag eine zusätzliche Prüfung auf das allow-Attribut durchführen.

<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

Anstatt den vorhandenen Code mit document zu aktualisieren, wird empfohlen, wie im vorherigen Beispiel allowsFeature() auf das element-Objekt anzuwenden.

Reporting API

Die Reporting API bietet einen einheitlichen Meldemechanismus für Webanwendungen. Die Reporting API für Verstöße gegen die Berechtigungsrichtlinien ist als experimentelle Funktion verfügbar.

Wenn Sie die experimentelle Funktion testen möchten, folgen Sie der Anleitung und aktivieren Sie das Flag in chrome://flags/#enable-experimental-web-platform-features. Wenn die Markierung aktiviert ist, können Sie Verstöße gegen die Berechtigungsrichtlinie in den DevTools auf dem Tab „Anwendung“ sehen:

Im folgenden Beispiel wird gezeigt, wie der Reporting API-Header aufgebaut sein kann:

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;

Bei der aktuellen Implementierung können Sie Berichte zu Richtlinienverstößen erhalten, die in diesem Frame auftreten, indem Sie einen Endpunkt mit dem Namen „default“ konfigurieren, wie im vorherigen Beispiel. Für Subframes ist eine eigene Berichtskonfiguration erforderlich.

Weitere Informationen

Weitere Informationen zur Berechtigungsrichtlinie finden Sie in den folgenden Ressourcen: