Browserfunktionen mit Berechtigungsrichtlinien steuern

Verwalten Sie, wie Ihre Seite und die iFrames von Drittanbietern auf Ihrer Seite auf Browserfunktionen zugreifen können.

Kevin K. Lee

Mit der Berechtigungsrichtlinie (früher „Funktionsrichtlinie“) können Entwickler die für eine Seite, die zugehörigen iFrames und Unterressourcen verfügbaren Browserfunktionen steuern, indem sie eine Reihe von Richtlinien deklarieren, die vom Browser erzwungen werden sollen. Diese Richtlinien werden auf Ursprünge angewendet, die in einer Ursprungsliste des Antwortheaders angegeben sind. Die Ursprungsliste kann dieselben und/oder ursprungsübergreifende Quellen enthalten und ermöglicht dem Entwickler, den eigenen und Drittanbieterzugriff auf Browserfunktionen zu steuern.

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

Durch die Berechtigungsrichtlinie kann die Website der obersten Ebene definieren, was sie und ihre Drittanbieter verwenden möchten. Außerdem muss der Nutzer nicht selbst bestimmen, ob die Anfrage für den Funktionszugriff legitim ist oder nicht. Wenn Sie beispielsweise die Funktion zur Standortbestimmung über die Berechtigungsrichtlinie für alle Drittanbieter blockieren, kann der Entwickler sicher sein, dass kein Dritter Zugriff auf die Standortbestimmung des Nutzers erhält.

Hinweis:Die Privacy Sandbox umfasst eine Reihe von Vorschlägen und APIs für Anwendungsfälle von Drittanbietern ohne Drittanbieter-Cookies oder andere Tracking-Mechanismen. Privacy Sandbox-APIs wie User-Agent-Client-Hints und die Topics API werden von der Berechtigungsrichtlinie auf die gleiche Weise verwaltet wie Funktionen wie geolocation und camera. Eine Liste der Webplattform-APIs, die auf Berechtigungsrichtlinien beruhen, finden Sie in der Liste der Funktionen. Hinweis: Diese Liste ist möglicherweise nicht aktuell.

Änderungen an der Richtlinie für Berechtigungen

Die Berechtigungsrichtlinie hieß früher „Funktionsrichtlinie“. Die Schlüsselkonzepte bleiben die gleichen, aber neben dem Namen gibt es einige wichtige Änderungen.

Verwendung von strukturierten Feldern

Strukturierte Felder bieten eine Reihe gängiger Datenstrukturen, um das Parsen und Serialisieren von HTTP-Header-Feldwerten zu standardisieren. Weitere Informationen zu Structured Fields finden Sie im Blogpost von Fastly „Improving HTTP withstructured header fields.

Alt

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

Vorher mit der Funktionsrichtlinie.

Neu

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

Jetzt mit Berechtigungsrichtlinie.

Header mit dem iFrame-Attribut allow kombinieren

Mit der Funktionsrichtlinie können Sie die Funktion 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 gemäß 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 Berechtigungsrichtlinien enthält, wird davon ausgegangen, dass die Ursprungsliste den Standardwert * hat. Wenn Sie das Attribut allow in den iFrame einfügen, können Sie auf die Funktion zugreifen.

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

Die Funktionsrichtlinie kann auch nach Chrome 88 verwendet werden, fungiert aber als Alias für die Richtlinie für Berechtigungen. Abgesehen von der Syntax gibt es keinen Unterschied in der Logik. Wenn sowohl die Header für die Berechtigungsrichtlinie als auch die Funktionsrichtlinie zusammen verwendet werden, hat der Header „Permissions-Policy“ eine höhere Priorität und überschreibt den Wert, der vom Header „Feature-Policy“ bereitgestellt wird.

Wie verwende ich die Berechtigungsrichtlinie?

Kurzübersicht

Bevor wir genauer ins Detail gehen, werfen wir einen kurzen Blick auf ein häufiges Szenario, bei dem Sie als Inhaber einer Website steuern möchten, wie Ihre Website und Drittanbietercode Browserfunktionen verwenden.

• Ihre Website hat den Status „https://your-site.example“.
• Auf Ihrer Website wird ein iFrame desselben Ursprungs (https://your-site.example) eingebettet.
• Auf deiner Website ist ein vertrauenswürdiger iFrame von https://trusted-site.example eingebettet.
• Auf Ihrer Website werden auch Anzeigen von https://ad.example ausgeliefert.
• 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")

Und setzen Sie das Attribut allow explizit auf das iFrame-Tag für die vertrauenswürdige Website:

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

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

1. Ihre Website your-site.example darf die Funktion zur Standortbestimmung mit Einwilligung des Nutzers verwenden.
2. Ein iFrame mit demselben Ursprung (your-site.example) darf die Funktion ohne das Attribut allow verwenden.
3. Ein iFrame, der von einer anderen Subdomain (subdomain.your-site-example) bereitgestellt wird, der nicht der Ursprungsliste hinzugefügt wurde und bei dem das „allow“-Attribut im iFrame-Tag festgelegt ist, kann die Funktion nicht verwenden. Verschiedene Subdomains gelten als dieselbe Website, aber ursprungsübergreifend.
4. Ein ursprungsübergreifender iFrame (trusted-site.example), der der Ursprungsliste hinzugefügt wurde und bei dem 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, kann die Funktion nicht verwenden, auch wenn das Attribut allow im iFrame-Tag enthalten ist.

Permissions-Policy-HTTP-Antwortheader

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

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

Wenn sich Ihre Kopfzeile auf mehrere Elemente bezieht, trennen Sie diese durch Kommas. Wenn Sie mehrere Ursprünge auflisten, trennen Sie sie in der Abreiseliste 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 sind einige Beispiele für Schlüssel/Wert-Paare:

• Syntax: [FEATURE]=*
  • Richtlinie auf alle Ursprünge angewendet
  • Beispiel: geolocation=*
• Syntax: [FEATURE]=(self)
  • Richtlinie für Same-Origin-Ansatz
  • Beispiel: geolocation=(self)
• Syntax: [FEATURE]=(self [ORIGIN(s)])
  • Richtlinie, die auf denselben 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 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 Einbettungsanbieters sein. Wenn die Einbettungsseite selbst keine Berechtigungen erhält, werden die auf dieser Seite eingebetteten iFrames ebenfalls blockiert, obwohl sie der Ursprungsliste hinzugefügt werden, da die Berechtigungsrichtlinie die Berechtigungen delegiert. Sie können auch das self-Token verwenden.
• Syntax: [FEATURE]=()
  • Funktion für alle Ursprünge blockiert
  • Beispiel: geolocation=()

Warnung:Wenn der Header für die Berechtigungsrichtlinie nicht in der Antwort vorhanden ist, wird der Standardwert das Token * verwendet. Dadurch kann die Funktion von allen iFrames auf der Seite mit einem allow-Attribut genutzt werden. Daher wird dringend empfohlen, die Ursprungsliste explizit im Berechtigungsrichtlinie-Header festzulegen, um den Zugriff zu steuern.

Wichtiger Hinweis:Mit der Änderung in der Berechtigungsrichtlinie der Funktionsrichtlinie reicht es nicht mehr aus, den Ursprung der Header-Ursprungsliste hinzuzufügen, um die Funktion für einen ursprungsübergreifenden iFrame zu aktivieren. Der iFrame muss das Attribut allow enthalten, wenn er ursprungsübergreifend ist, unabhängig davon, was in der Header-Ursprungsliste festgelegt ist.

Verschiedene Subdomains und Pfade

Verschiedene Subdomains wie https://your-site.example und https://subdomain.your-site.example gelten als dieselbe Website, aber ursprungsübergreifend. Wenn Sie der Ursprungsliste eine Subdomain hinzufügen, können Sie daher nicht auf eine andere Subdomain derselben Website zugreifen. Jede eingebettete Subdomain, die die Funktion verwenden möchte, muss separat der Ursprungsliste hinzugefügt werden. Wenn beispielsweise der Zugriff auf die Browserthemen des Nutzers mit demselben Ursprung nur mit dem Header Permissions-Policy: browsing-topics=(self) möglich ist, hat ein iFrame aus 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. Unterschiedliche Pfade müssen nicht in der Ursprungsliste aufgeführt werden.

iFrame-Attribut allow

Bei der ursprungsübergreifenden Nutzung benötigt ein iFrame das Attribut allow im Tag, um Zugriff auf die Funktion zu erhalten.

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

Beispiel:

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

Hinweis:Die Syntax allow="geolocation" ist eine Abkürzung für „allow="geolocation 'src'". „src“ ist ein spezielles Token, das zum Ursprung des src-Attributs des iFrames erweitert wird.

iFrame-Navigation verarbeiten

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 den Ursprung, zu dem der iFrame navigiert, im Attribut allow auflisten, wird die auf den ursprünglichen iFrame angewendete Berechtigungsrichtlinie auf den Ursprung angewendet, zu dem der iFrame führt.

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

Um es in Aktion zu erleben, sehen Sie sich die Demo der iFrame-Navigation an.

Beispiele für die Konfiguration von Berechtigungsrichtlinien

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

Funktion an allen Ursprüngen 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 festgelegt ist, ist die Funktion für alle auf der Seite vorhandenen Ursprünge zulässig, einschließlich sich selbst und aller iFrames. In diesem Beispiel haben alle Codes, die über https://your-site.example bereitgestellt werden, und die Codes, die vom iFrame https://trusted-site.example und https://ad.example bereitgestellt werden, Zugriff auf die Funktion zur Standortbestimmung im Browser des Nutzers. Denken Sie daran, dass das Attribut „allow“ auch im iFrame selbst festgelegt werden muss, während der Ursprung zur Ursprungsliste des Headers hinzugefügt wird.

Wie das geht, erfährst du in der Demo.

Funktion nur am selben Ursprung zulässig

Permissions-Policy: geolocation=(self)

Die Verwendung des self-Tokens ermöglicht die Standortbestimmung am selben Ursprung. 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 die Funktion nur für Ihre Seite und sonst nicht verwendet werden soll.

Wie das geht, erfährst du in der Demo.

Funktion für denselben Ursprung und bestimmte ursprungsübergreifende Optionen zulässig

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, das Attribut „allow“ explizit in das iFrame-Tag einzufügen. Wenn ein weiterer iFrame mit <iframe src="https://ad.example" allow="geolocation"> vorhanden ist, hat https://ad.example keinen Zugriff auf die Funktion zur Standortbestimmung. 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.

Wie das geht, erfährst du in der Demo.

Funktion für alle Ursprünge blockiert

Permissions-Policy: geolocation=()

Bei einer leeren Ursprungsliste wird die Funktion für alle Ursprünge blockiert. Wie das geht, erfährst du in der Demo.

Wichtiger Hinweis:Die Funktion kann nicht für eingebettete ursprungsübergreifende Elemente zugelassen werden, wenn das Element für Same-Origin blockiert ist. Da die für die übergeordnete Seite angewendeten Berechtigungen an die eingebetteten iFrames delegiert werden, muss die Funktion für Same-Origin aktiviert sein, wenn die Funktion für ursprungsübergreifende Zugriffe zugelassen werden soll.

JavaScript API verwenden

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

Die Feature Policy API kann mit einigen Einschränkungen für über die Berechtigungsrichtlinie festgelegte Richtlinien verwendet werden. Es gibt noch einige Fragen zu einer JavaScript API-Implementierung und es wurde ein Vorschlag gemacht, die Logik in die Permissions API zu verschieben. Nehmen Sie an der Diskussion teil, wenn Sie eine Idee haben.

featurePolicy.allowsFeature(feature)

• Gibt true zurück, wenn das Feature für die Verwendung des Standardabsprungs zulässig ist.
• Das Verhalten ist für beide Richtlinien, die durch 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

featuresPolicy.allowsFeature(feature, origin)

• Gibt true zurück, wenn das Element für den angegebenen Ursprung zulässig ist.
• Wenn die Methode unter document aufgerufen wird, gibt diese Methode nicht mehr Aufschluss darüber, ob die Funktion für den angegebenen Ursprung zulässig ist, wie es die Funktionsrichtlinie getan hat. 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 das Attribut allow des iFrame-Elements zusätzlich prüfen, um festzustellen, ob die Funktion für die Drittanbieterquelle zulässig ist.

Mit dem element-Objekt nach Funktionen in einem iFrame 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 das 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 Standardursprungs zulässig sind
• Das Verhalten ist für beide Richtlinien, die durch die Berechtigungsrichtlinie und die Funktionsrichtlinie festgelegt werden, identisch.
• 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, die durch die Berechtigungsrichtlinie und die Funktionsrichtlinie festgelegt werden, identisch.

Einbindung der Chrome-Entwicklertools

So funktioniert die Berechtigungsrichtlinie in den Entwicklertools.

1. Öffnen Sie die Chrome-Entwicklertools.
2. Öffnen Sie das Steuerfeld 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. Es wird eine Liste der Elemente angezeigt, die der ausgewählte Frame verwenden darf, sowie eine Liste der Elemente, die in diesem Frame blockiert sind.

Migration von Feature-Richtlinie

Wenn Sie derzeit den Header Feature-Policy verwenden, können Sie die folgenden Schritte zur Migration zur Berechtigungsrichtlinie implementieren.

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

Da die Header für Funktionsrichtlinien nur in Chromium-basierten Browsern unterstützt werden und Header für Berechtigungsrichtlinien seit Chrome 88, können Sie die vorhandenen Header ohne Bedenken mit Berechtigungsrichtlinien aktualisieren.

Alt

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

Vorher mit der Funktionsrichtlinie.

Neu

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

Jetzt mit Berechtigungsrichtlinie.

Nutzung von document.allowsFeature(feature, origin) aktualisieren

Wenn Sie die Methode document.allowsFeature(feature, origin) verwenden, um die zulässigen Funktionen für iFrames zu prüfen, verwenden Sie die Methode allowsFeature(feature), 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) hingegen nicht.

Funktionszugriff wird bei document geprüft

Wenn Sie document weiterhin als Basisknoten verwenden möchten, müssen Sie das Attribut allow im iFrame-Tag zusätzlich prüfen.

<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() für das element-Objekt wie im vorherigen Beispiel aufzurufen.

Reporting API

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

Wenn du die experimentelle Funktion testen möchtest, folge der Schritt-für-Schritt-Anleitung und aktiviere das Flag in chrome://flags/#enable-experimental-web-platform-features. Wenn das Flag aktiviert ist, können Sie Verstöße gegen Berechtigungsrichtlinien in den Entwicklertools auf dem Tab „Anwendung“ sehen:

Das folgende Beispiel zeigt, 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;

In der aktuellen Implementierung können Sie Berichte zu Richtlinienverstößen zu allen Verstößen in diesem Frame erhalten, indem Sie wie im obigen Beispiel einen Endpunkt mit dem Namen „Standard“ konfigurieren. Für Subframes ist eine eigene Berichtskonfiguration erforderlich.

Hinweis:Wenn Sie möchten, dass die Unterstützung für Berechtigungsrichtlinien standardmäßig in der Reporting API angezeigt wird, fügen Sie den entsprechenden Support oder Ihre Kommentare zur Diskussion hinzu.

Weitere Informationen

Detaillierte Informationen zur Berechtigungsrichtlinie finden Sie in den folgenden Ressourcen:

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