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

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 denselben Ursprung und/oder ursprungsübergreifende Quellen enthalten und ermöglicht dem Entwickler, den Zugriff von Erst- und Drittanbietern auf Browserfunktionen zu steuern.

Der Nutzer entscheidet selbst, ob er den Zugriff auf leistungsstärkere Funktionen zulassen möchte. Er muss eine ausdrückliche 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ß zuvor „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.

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

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

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 ursprungsübergreifenden Frame 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 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 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 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 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.
• 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 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 Attribut allow explizit auf das iFrame-Tag für die vertrauenswürdige Website fest:

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

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 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. 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 für das Iframe-Tag festgelegt ist, ist die Verwendung der Funktion zulässig.
5. Ein ursprungsübergreifender iFrame (trusted-site.example), der der Ursprungsliste ohne das Attribut allow 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

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. Bei Headern, die einen Ursprung für eine Cross-Origin-Anfrage angeben, muss das iframe-Tag das Attribut allow enthalten.

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

• Syntax: [FEATURE]=*
  • Richtlinie wird auf alle Ursprünge angewendet
  • Beispiel: geolocation=*
• Syntax: [FEATURE]=(self)
  • Richtlinie auf „Same-Origin“ angewendet
  • Beispiel: geolocation=(self)
• Syntax: [FEATURE]=(self [ORIGIN(s)])
  • 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)])
  • Richtlinie, die auf denselben Ursprung und die angegebenen Ursprünge angewendet wird
  • 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 der Zugriff auf die Themen des Nutzers beispielsweise 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.

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

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 verwenden

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 iFrame-Navigation können Sie sich die Funktion in Aktion 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

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 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.

Feature nur für denselben Ursprung zulässig

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 Sie die Funktion nur für Ihre Seite nutzen möchten.

Diese Konfiguration ist in der Demo zu sehen.

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

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 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 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

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 Funktionshinweisrichtlinie 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. Beteiligen Sie sich an der Diskussion, wenn Sie Ideen haben.

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, 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“ für den 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 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.

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

Chrome-Entwicklertools-Integration

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 mit den folgenden Schritten zur Berechtigungsrichtlinie migrieren.

Header der Richtlinien zu Funktionen durch Header der 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.

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=()

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 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, 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. Subframes benötigen eine eigene Berichtskonfiguration.

Weitere Informationen

Weitere Informationen zur Berechtigungsrichtlinie finden Sie in den folgenden Ressourcen:

• Spezifikationen der Berechtigungsrichtlinie
• Erläuterung der Berechtigungsrichtlinien
• Eine Liste der richtliniengesteuerten Funktionen.