Browserfunktionen mit Berechtigungsrichtlinien steuern

Legen Sie fest, wie Ihre Seite und Drittanbieter-iFrames auf Ihrer Seite Zugriff auf Browserfunktionen haben.

Kevin K. Lee
Kevin K. Lee
X GitHub

„Berechtigungsrichtlinie“ (früher „Funktionsrichtlinie“) ermöglicht Entwicklern, die für eine Seite, deren iFrames und untergeordneten Ressourcen, indem eine Reihe von Richtlinien deklariert wird, die vom Browser erzwungen werden sollen. Diese Richtlinien werden auf Ursprünge angewendet, die in einer Ursprungsliste eines Antwortheaders angegeben sind. Die Ursprungsliste kann Same- und/oder Cross-Origins enthalten kann der Entwickler den Zugriff von Erst- und Drittanbietern auf Browserfunktionen steuern.

Der Nutzer trifft die endgültige Entscheidung, ob er Zugriff auf leistungsfähigere Funktionen gewährt, und muss ihm über eine Aufforderung eine ausdrückliche Genehmigung erteilen.

Mit der Richtlinie für Berechtigungen kann die übergeordnete Website definieren, die Sie nutzen möchten, und entlastet die Nutzenden, ob die Anfrage für den Funktionszugriff berechtigt ist oder nicht. Wenn Sie beispielsweise die Standortbestimmung für alle Drittanbieter über die Richtlinie für Berechtigungen blockiert, kann der Entwickler sicher sein, dass kein Dritter Zugriff auf die Standortbestimmung.

Änderungen an der Richtlinie für Berechtigungen

Berechtigungsrichtlinie hieß zuvor „Funktionsrichtlinie“. Die wichtigsten Konzepte bleiben unverändert, aber neben dem Namen gibt es einige wichtige Änderungen.

Verwendung strukturierter Felder

Strukturierte Felder bieten eine Reihe allgemeiner Datenstrukturen, um das Parsen und die Serialisierung von HTTP-Header-Feldwerten zu standardisieren. Weitere Informationen zu strukturierten Feldern finden Sie im Fastly-Blogpost „Improving HTTP withstructured header fields“.

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

Vorher mit Funktionsrichtlinie.

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

Jetzt mit Berechtigungsrichtlinie.

Header mit dem iFrame-Attribut allow kombinieren

Mit der Funktionsrichtlinie können Sie das Element einem ursprungsübergreifenden Frame hinzufügen, indem Sie den Ursprung entweder der Header-Ursprungsliste hinzufügen oder dem iFrame-Tag ein allow-Attribut hinzufügen. Wenn Sie der Ursprungsliste mit der Berechtigungsrichtlinie einen ursprungsübergreifenden Frame hinzufügen, muss das iFrame-Tag für diesen Ursprung das Attribut allow enthalten. Wenn die Antwort keinen Header für die Berechtigungsrichtlinie enthält, wird davon ausgegangen, dass die Ursprungsliste den Standardwert * hat. Wenn Sie dem iFrame das Attribut allow hinzufügen, kann auf die Funktion zugegriffen werden.

Daher empfehlen wir Entwicklern, den Header für die Berechtigungsrichtlinie explizit in der Antwort festzulegen. So wird verhindert, dass ursprungsübergreifende iFrames, die nicht in der Ursprungsliste aufgeführt sind, auf diese Funktion zugreifen können, selbst wenn allow vorhanden ist.

Die Funktionsrichtlinie 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 der Header „Berechtigungsrichtlinie“ und „Funktionsrichtlinie“ zusammen verwendet wird, hat der Header „Permissions-Policy“ eine höhere Priorität und überschreibt den Wert des Headers „Feature-Policy“.

Wie verwende ich die Richtlinie für Berechtigungen?

Kurzer Überblick

Bevor wir näher auf das Thema eingehen, werfen wir zunächst einen kurzen Blick auf ein häufiges Szenario, bei dem Sie als Inhaber einer Website kontrollieren möchten, wie Ihre Website und der Code von Drittanbietern Browserfunktionen verwenden.

  • Ihre Website ist https://your-site.example.
  • Auf Ihrer Website ist ein iFrame desselben Ursprungs (https://your-site.example) eingebettet.
  • Auf deiner Website ist ein iFrame von https://trusted-site.example eingebettet, dem du vertraust.
  • Auf Ihrer Website werden auch Anzeigen ausgeliefert, die von https://ad.example ausgeliefert wurden.
  • 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 Attribut allow explizit auf das iFrame-Tag für die vertrauenswürdige Website fest:

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

Kurzer Überblick über die Verwendung der Berechtigungsrichtlinie.

In diesem Beispiel können in der Ursprungsliste des Headers nur Ihre Website (self) und trusted-site.example die Geolokalisierungsfunktion verwenden. ad.example darf die Standortbestimmung nicht verwenden.

  1. Ihre Website your-site.example darf die Standortbestimmungsfunktion mit Zustimmung des Nutzers verwenden.
  2. In einem iFrame am selben Ursprung (your-site.example) darf die Funktion ohne das Attribut allow verwendet werden.
  3. Ein iFrame, der von einer anderen Subdomain ausgeliefert wird (subdomain.your-site-example), die nicht der Ursprungsliste hinzugefügt wurde und für die das Attribut „allow“ im iFrame-Tag festgelegt ist, kann die Funktion nicht verwenden. Verschiedene Subdomains werden als ursprungsübergreifend, aber auf derselben Website betrachtet.
  4. Ein ursprungsübergreifender iFrame (trusted-site.example), der der Ursprungsliste hinzugefügt wurde und für den das Attribut allow im iFrame-Tag festgelegt ist, darf die Funktion verwenden.
  5. Ein ursprungsübergreifender iFrame (trusted-site.example), der der Ursprungsliste ohne das Attribut allow hinzugefügt wurde, kann die Funktion nicht verwenden.
  6. Ein ursprungsübergreifender iFrame (ad.example), der nicht der Ursprungsliste hinzugefügt wurde, wird daran gehindert, die Funktion zu verwenden, auch wenn das Attribut allow im iFrame-Tag enthalten ist.

HTTP-Antwortheader „Permissions-Policy“

Der Nutzer stellt eine Anfrage, der Server antwortet mit dem Header für die Berechtigungsrichtlinie und der Browser gewährt basierend auf diesem Header Zugriff.

Permissions-Policy: &lt;feature&gt;=(&lt;token&gt;|&lt;origin(s)&gt;)

Verwenden Sie einen Permissions-Policy-Header in der Antwort des Servers, um die zulässigen Ursprünge für ein Element festzulegen. Der Headerwert kann eine Kombination aus Tokens und Ursprungsstrings annehmen. Die verfügbaren Tokens sind * für alle Ursprünge und self für denselben Ursprung.

Wenn sich die Kopfzeile auf mehrere Elemente bezieht, trennen Sie sie durch Kommas. Wenn Sie mehrere Ursprünge auflisten, trennen Sie die einzelnen Ursprünge in der Ursprungsliste durch ein Leerzeichen. Für Header mit einem Ursprung, bei dem es sich um eine ursprungsübergreifende Anfrage handelt, muss das iFrame-Tag das Attribut allow enthalten.

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

  • Syntax: [FEATURE]=* <ph type="x-smartling-placeholder">
      </ph>
    • Richtlinie wird auf alle Ursprünge angewendet
    • Beispiel: geolocation=*
  • Syntax: [FEATURE]=(self) <ph type="x-smartling-placeholder">
      </ph>
    • Richtlinie wird auf denselben Ursprung angewendet
    • Beispiel: geolocation=(self)
  • Syntax: [FEATURE]=(self [ORIGIN(s)]) <ph type="x-smartling-placeholder">
      </ph>
    • Richtlinie, die auf denselben Ursprung und die angegebenen Ursprünge angewendet wird
    • Beispiel: geolocation=(self "https://a.example" "https://b.example")
    • self ist eine Abkürzung für https://your-site.example
  • Syntax: [FEATURE]=([ORIGIN(s)]) <ph type="x-smartling-placeholder">
      </ph>
    • Richtlinie, die auf denselben Ursprung und die angegebenen Ursprünge angewendet wird
    • Beispiel: geolocation=("https://your-site.example" "https://a.example" "https://b.example")
    • Wenn Sie diese Syntax verwenden, muss einer der Ursprünge der Ursprung des Einbettungselements sein. Wenn der eingebetteten Seite selbst die Berechtigungen nicht gewährt werden, werden auch die in diese Seite eingebetteten iFrames blockiert, obwohl sie der Ursprungsliste hinzugefügt wurden, da die Berechtigungsrichtlinie Berechtigungen delegiert. Sie können auch das Token self verwenden.
  • Syntax: [FEATURE]=() <ph type="x-smartling-placeholder">
      </ph>
    • Funktion für alle Ursprünge blockiert
    • Beispiel: geolocation=()

Verschiedene Subdomains und Pfade

Verschiedene Subdomains wie https://your-site.example und https://subdomain.your-site.example werden als gleiche Website, aber ursprungsübergreifend betrachtet. Wenn Sie also eine Subdomain der Ursprungsliste hinzufügen, wird der Zugriff auf eine andere Subdomain derselben Website nicht ermöglicht. Jede eingebettete Subdomain, die diese Funktion verwenden möchte, muss separat zur Ursprungsliste hinzugefügt werden. Wenn beispielsweise der Zugriff auf die Browserthemen des Nutzers nur über den Header „Permissions-Policy: browsing-topics=(self)“ am selben Ursprung erlaubt ist, hat ein iFrame von einer anderen Subdomain derselben Website (https://subdomain.your-site.example) keinen Zugriff auf die Themen.

Verschiedene Pfade wie https://your-site.example und https://your-site.example/embed werden als derselbe Ursprung betrachtet und unterschiedliche Pfade müssen nicht in der Ursprungsliste aufgeführt werden.

iFrame-Attribut allow

iFrames einrichten

Für die ursprungsübergreifende Nutzung benötigt ein iFrame das Attribut allow im Tag, um auf die Funktion zugreifen zu können.

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

Beispiel:

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

iFrame-Navigation

iFrame-Navigation einrichten

Wenn ein iFrame zu einem anderen Ursprung navigiert, wird die Richtlinie standardmäßig nicht auf den Ursprung angewendet, zu dem der iFrame navigiert. Wenn Sie im Attribut allow den Ursprung auflisten, zu dem der iFrame navigiert, wird die Berechtigungsrichtlinie, die auf den ursprünglichen iFrame angewendet wurde, auf den Ursprung angewendet, zu dem der iFrame navigiert.

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

Sehen Sie sich dazu die Demo für die iFrame-Navigation an.

Beispiele für die Einrichtung einer Berechtigungsrichtlinie

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

Element für alle Ursprünge zugelassen

Architektur aller Ursprünge, die auf das Feature 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 * gesetzt ist, ist das Element für alle Ursprünge auf der Seite zulässig, einschließlich sich selbst und alle iFrames. In diesem Beispiel haben alle von https://your-site.example bereitgestellten Codes und die von https://trusted-site.example iFrame und https://ad.example bereitgestellten Codes Zugriff auf die Funktion zur Standortbestimmung im Browser des Nutzers. Denken Sie daran, dass das Attribut „allow“ auch im iFrame selbst festgelegt werden muss, zusammen mit dem Hinzufügen des Ursprungs zur Ursprungsliste des Headers.

Diese Konfiguration können Sie sich in der Demo ansehen.

Feature nur für denselben Ursprung zulässig

Architektur nur desselben Ursprungs, die auf das Feature zugreifen darf

Permissions-Policy: geolocation=(self)

Wenn Sie das Token self verwenden, können Sie die Standortbestimmung nur für denselben Ursprung verwenden. Ursprungsübergreifende Nutzer 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 Sie die Funktion nur für Ihre Seite nutzen möchten.

Diese Konfiguration können Sie sich in der Demo ansehen.

Feature für denselben Ursprung und bestimmte ursprungsübergreifende Elemente zulässig

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

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

Diese Syntax ermöglicht die Verwendung der Standortbestimmung sowohl für sich selbst (https://your-site.example) als auch für https://trusted-site.example. Denken Sie daran, dem iFrame-Tag explizit 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 Originalseite und die 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 können Sie sich in der Demo ansehen.

Funktion für alle Ursprünge blockiert

Architektur aller Ursprünge, die keinen Zugriff auf das Feature haben

Permissions-Policy: geolocation=()

Bei einer leeren Ursprungsliste wird das Element für alle Ursprünge blockiert. Diese Konfiguration können Sie sich in der Demo ansehen.

JavaScript API verwenden

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

Die Feature Policy API kann mit einigen Einschränkungen für durch Berechtigungsrichtlinien festgelegte Richtlinien verwendet werden. Es gibt noch weitere Fragen zu einer JavaScript API-Implementierung und ein Angebot wurde unterbreitet, die Logik in die Permissions API zu verschieben. Beteiligen Sie sich an der Diskussion, wenn Sie Ideen haben.

featurePolicy.allowsFeature(feature)

  • Gibt true zurück, wenn das Feature für die Verwendung des Standardursprungs zulässig ist.
  • Das Verhalten ist für beide Richtlinien, die über die Berechtigungsrichtlinie und die vorherige Funktionsrichtlinie festgelegt wurden, identisch.
  • Wenn allowsFeature() für ein iFrame-Element (iframeEl.featurePolicy.allowsFeature('geolocation')) aufgerufen wird, gibt der zurückgegebene Wert an, ob das Attribut „allow“ im iFrame festgelegt ist

featurePolicy.allowsFeature(feature, origin)

  • Gibt true zurück, wenn das Element für den angegebenen Startort zulässig ist.
  • Wenn die Methode unter document aufgerufen wird, teilt sie Ihnen nicht mehr mit, ob das Element wie die Funktionsrichtlinie für den angegebenen Ursprung zulässig ist. Diese Methode teilt Ihnen nun mit, dass das Element für diesen Ursprung zugelassen werden kann. Sie müssen zusätzlich prüfen, ob für den iFrame das Attribut allow festgelegt ist. Der Entwickler muss zusätzlich das Attribut allow im iFrame-Element prüfen, um festzustellen, ob die Funktion für die Quelle des Drittanbieters zulässig ist.

Mit dem Objekt element in einem iFrame nach Funktionen suchen

Sie können element.allowsFeature(feature) verwenden, bei dem das Attribut „allow“ berücksichtigt wird, anders als bei document.allowsFeature(feature, origin).

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 Standardursprungs zulässig sind.
  • Das Verhalten ist für beide Richtlinien gleich, die über die Berechtigungsrichtlinie und die Funktionsrichtlinie festgelegt werden.
  • Wenn der verknüpfte 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 gleich, die über die Berechtigungsrichtlinie und die Funktionsrichtlinie festgelegt werden.

Einbindung in Chrome-Entwicklertools

Einbindung von Chrome-Entwicklertools in Berechtigungsrichtlinie

Hier erfährst du, wie Berechtigungsrichtlinien in den Entwicklertools funktionieren.

  1. Öffnen Sie die Chrome-Entwicklertools.
  2. Öffnen Sie das Steuerfeld Anwendung, um die zulässigen und unzulässigen Funktionen der einzelnen Frames zu überprüfen.
  3. Wählen Sie in der Seitenleiste den Frame aus, den Sie sich genauer ansehen möchten. Es wird eine Liste der Funktionen angezeigt, die der ausgewählte Frame verwenden darf, sowie eine Liste der Funktionen, die in diesem Frame blockiert sind.

Migration von Feature-Richtlinie

Wenn du aktuell den Feature-Policy-Header verwendest, kannst du die folgenden Schritte ausführen, um zur Berechtigungsrichtlinie zu migrieren.

Header für Funktionsrichtlinien durch Header für Berechtigungsrichtlinien ersetzen

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

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

Vorher mit Funktionsrichtlinie.

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

Jetzt mit Berechtigungsrichtlinie.

document.allowsFeature(feature, origin)-Nutzung 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 enthaltende document. Die Methode element.allowsFeature(feature) berücksichtigt das Attribut „allow“, document.allowsFeature(feature, origin) dies nicht.

Der Funktionszugriff wird von document geprüft

Wenn Sie document weiterhin als Basisknoten verwenden möchten, müssen Sie eine zusätzliche Prüfung auf das Attribut allow im iFrame-Tag 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, allowsFeature() wie im vorherigen Beispiel für das element-Objekt aufzurufen.

Reporting API

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

Wenn Sie die experimentelle Funktion testen möchten, folgen Sie der Schritt-für-Schritt-Anleitung und aktivieren Sie die Kennzeichnung in chrome://flags/#enable-experimental-web-platform-features. Wenn das Flag aktiviert ist, kannst du Verstöße gegen Berechtigungsrichtlinien in den Entwicklertools auf dem Tab „Anwendung“ beobachten:

Das folgende Beispiel zeigt, wie der Header der Reporting API 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;

In der aktuellen Implementierung können Sie Berichte zu Richtlinienverstößen für alle in diesem Frame auftretenden Verstöße erhalten, indem Sie einen Endpunkt namens „default“ konfigurieren wie im Beispiel oben. Subframes benötigen eine eigene Berichtskonfiguration.

Weitere Informationen

Weitere Informationen zu Berechtigungsrichtlinien finden Sie in den folgenden Ressourcen: