Legen Sie fest, wie Ihre Seite und Drittanbieter-iFrames auf Ihrer Seite Zugriff auf Browserfunktionen haben.
„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“.
geolocation 'self' https://example.com; camera 'none'
Vorher mit Funktionsrichtlinie.
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">
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.
- Ihre Website
your-site.example
darf die Standortbestimmungsfunktion mit Zustimmung des Nutzers verwenden. - In einem iFrame am selben Ursprung (
your-site.example
) darf die Funktion ohne das Attributallow
verwendet werden. - 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. - Ein ursprungsübergreifender iFrame (
trusted-site.example
), der der Ursprungsliste hinzugefügt wurde und für den das Attributallow
im iFrame-Tag festgelegt ist, darf die Funktion verwenden. - Ein ursprungsübergreifender iFrame (
trusted-site.example
), der der Ursprungsliste ohne das Attributallow
hinzugefügt wurde, kann die Funktion nicht verwenden. - Ein ursprungsübergreifender iFrame (
ad.example
), der nicht der Ursprungsliste hinzugefügt wurde, wird daran gehindert, die Funktion zu verwenden, auch wenn das Attributallow
im iFrame-Tag enthalten ist.
HTTP-Antwortheader „Permissions-Policy
“
Permissions-Policy: <feature>=(<token>|<origin(s)>)
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ürhttps://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
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
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
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
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
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
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 Attributallow
festgelegt ist. Der Entwickler muss zusätzlich das Attributallow
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
Hier erfährst du, wie Berechtigungsrichtlinien in den Entwicklertools funktionieren.
- Öffnen Sie die Chrome-Entwicklertools.
- Öffnen Sie das Steuerfeld Anwendung, um die zulässigen und unzulässigen Funktionen der einzelnen Frames zu überprüfen.
- 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.
Feature-Policy: autoplay *; geolocation 'self'; camera 'self' 'https://trusted-site.example'; fullscreen 'none';
Vorher mit Funktionsrichtlinie.
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: