Permissions-Policy header

Syntax

Permissions-Policy: <directive>=<allowlist>

<directive>

Die Permissions-Policy-Direktive, auf die die allowlist angewendet werden soll. Weitere Informationen finden Sie unter Directives unten für eine Liste der zugelassenen Direktivnamen.

<allowlist>

Eine Allowlist ist eine Liste von Ursprüngen, die einen oder mehrere der folgenden Werte in Klammern enthält, getrennt durch Leerzeichen:

* (Wildcard)

Die Funktion wird in diesem Dokument und in allen geschachtelten Browsing-Kontexten (<iframe>s) unabhängig von ihrem Ursprung erlaubt.

() (leere Allowlist)

Die Funktion ist in obersten und geschachtelten Browsing-Kontexten deaktiviert. Das Äquivalent für <iframe>-allow-Attribute ist 'none'.

self

Die Funktion wird in diesem Dokument und in allen geschachtelten Browsing-Kontexten (<iframe>s) im selben Ursprung erlaubt. Die Funktion ist in fremden Dokumenten in geschachtelten Browsing-Kontexten nicht erlaubt. self kann als Abkürzung für https://your-site.example.com betrachtet werden. Das Äquivalent für <iframe>-allow-Attribute ist self.

src

Die Funktion wird in diesem <iframe> erlaubt, solange das darin geladene Dokument vom selben Ursprung wie die URL in seinem src-Attribut stammt. Dieser Wert wird nur im <iframe>-allow-Attribut verwendet und ist der default allowlist-Wert in <iframe>s.

"<origin>"

Die Funktion ist für bestimmte Ursprünge erlaubt (zum Beispiel "https://a.example.com"). Ursprünge sollten durch Leerzeichen getrennt werden. Beachten Sie, dass Ursprünge in <iframe>-Allow-Attributen nicht in Anführungszeichen stehen.

Die Werte * und () dürfen nur allein verwendet werden, während self und src in Kombination mit einem oder mehreren Ursprüngen verwendet werden können.

Hinweis: Direktiven haben eine Standard-Allowlist, die immer einer von *, self oder none für den Permissions-Policy HTTP-Header ist, und die das Standardverhalten regelt, wenn sie nicht explizit in einer Richtlinie aufgeführt sind. Diese sind auf den einzelnen Richtlinien-Referenzseiten angegeben. Für <iframe>-allow-Attribute ist das Standardverhalten immer src.

Wo unterstützt, können Sie Wildcards in Permissions-Policy-Ursprüngen einschließen. Das bedeutet, dass Sie anstatt mehrerer verschiedener Subdomains explizit in einer Allowlist anzugeben, alle in einem einzigen Ursprung mit Wildcard angeben können.

Stattdessen:

("https://example.com" "https://a.example.com" "https://b.example.com" "https://c.example.com")

Können Sie angeben:

("https://example.com" "https://*.example.com")

Direktiven

accelerometer Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, Informationen über die Beschleunigung des Geräts über die Accelerometer-Schnittstelle zu sammeln.

ambient-light-sensor Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, Informationen über die Lichtmenge in der Umgebung des Geräts mithilfe der AmbientLightSensor-Schnittstelle zu sammeln.

aria-notify Experimentell Nicht standardisiert

Steuert, ob dem aktuellen Dokument erlaubt ist, die ariaNotify()-Methode zu verwenden, um Screenreader-Ankündigungen auszulösen.

attribution-reporting Experimentell

Steuert, ob dem aktuellen Dokument die Nutzung der Attribution Reporting API erlaubt ist.

autoplay Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, Medien abzuspielen, die über die HTMLMediaElement-Schnittstelle angefordert werden. Wenn diese Richtlinie deaktiviert ist und keine Nutzerinteraktionen vorliegen, wird das von HTMLMediaElement.play() zurückgegebene Promise mit einem NotAllowedError DOMException abgelehnt. Das Autoplay-Attribut auf <audio> und <video>-Elementen wird ignoriert.

bluetooth Experimentell

Steuert, ob die Nutzung der Web Bluetooth API erlaubt ist. Wenn diese Richtlinie deaktiviert ist, werden die Methoden des Bluetooth-Objekts, das von Navigator.bluetooth zurückgegeben wird, entweder false zurückgeben oder das zurückgegebene Promise mit einem SecurityError DOMException ablehnen.

browsing-topics Experimentell Nicht standardisiert

Steuert den Zugriff auf die Topics API. Wenn eine Richtlinie die Nutzung der Topics API ausdrücklich untersagt, schlagen alle Versuche, die Document.browsingTopics()-Methode aufzurufen oder eine Anfrage mit einem Sec-Browsing-Topics-Header zu senden, mit einem NotAllowedError DOMException fehl.

camera Experimentell

Steuert, ob dem aktuellen Dokument die Nutzung von Videoeingabegeräten erlaubt ist. Das Promise, das von getUserMedia() zurückgegeben wird, wird mit einem NotAllowedError DOMException abgelehnt, wenn die Erlaubnis nicht erteilt wurde.

captured-surface-control Experimentell

Steuert, ob das Dokument die Captured Surface Control API verwenden darf. Das von den Hauptmethoden der API zurückgegebene Versprechen wird mit einem NotAllowedError DOMException abgelehnt, wenn die Erlaubnis nicht erteilt wurde.

compute-pressure Experimentell

Steuert den Zugriff auf die Compute Pressure API.

cross-origin-isolated Experimentell

Steuert, ob das aktuelle Dokument als cross-origin isolated behandelt werden kann.

deferred-fetch Experimentell

Steuert die Zuweisung des fetchLater()-Kontingents für den obersten Ursprung.

deferred-fetch-minimal Experimentell

Steuert die Zuweisung des geteilten fremd-originären Unterrahmen- fetchLater()-Kontingents.

display-capture Experimentell

Steuert, ob dem aktuellen Dokument die Nutzung der getDisplayMedia()-Methode zur Aufnahme von Bildschirm-Inhalten gestattet ist. Wenn diese Richtlinie deaktiviert ist, wird das von getDisplayMedia() zurückgegebene Versprechen mit einem NotAllowedError DOMException abgelehnt, wenn keine Berechtigung zur Erfassung des Bildschirminhalts erteilt wird.

encrypted-media Experimentell

Steuert, ob dem aktuellen Dokument die Nutzung der Encrypted Media Extensions API (EME) erlaubt ist. Wenn diese Richtlinie deaktiviert ist, wird das von Navigator.requestMediaKeySystemAccess() zurückgegebene Promise mit einem SecurityError DOMException abgelehnt.

fullscreen Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, Element.requestFullscreen() zu verwenden. Wenn diese Richtlinie deaktiviert ist, wird das zurückgegebene Promise mit einem TypeError abgelehnt.

gamepad Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, die Gamepad API zu verwenden. Wenn diese Richtlinie deaktiviert ist, werden Anrufe an Navigator.getGamepads() einen SecurityError DOMException auslösen, und die gamepadconnected und gamepaddisconnected-Ereignisse werden nicht ausgelöst.

geolocation Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, die Geolocation-Schnittstelle zu verwenden. Wenn diese Richtlinie deaktiviert ist, führen Anrufe an getCurrentPosition() und watchPosition() dazu, dass die Rückruf-Funktionen dieser Methoden mit einem GeolocationPositionError-Code von PERMISSION_DENIED aufgerufen werden.

gyroscope Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, Informationen über die Ausrichtung des Geräts über die Gyroscope-Schnittstelle zu sammeln.

hid Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, die WebHID API zu verwenden, um sich mit ungewöhnlichen oder exotischen Human Interface Devices, wie alternativen Tastaturen oder Gamepads, zu verbinden.

identity-credentials-get Experimentell

Steuert, ob dem aktuellen Dokument die Nutzung der Federated Credential Management API (FedCM) erlaubt ist.

idle-detection Experimentell

Steuert, ob dem aktuellen Dokument die Nutzung der Idle Detection API zum Erkennen von Benutzerinteraktionen mit ihren Geräten, z. B. um den "verfügbar"/"abwesend"-Status in Chat-Anwendungen zu melden, erlaubt ist.

language-detector Experimentell

Steuert den Zugriff auf die Sprachenerkennungsfunktionalität der Translator and Language Detector APIs.

local-fonts Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, Daten über die lokal installierten Schriften des Benutzers über die Window.queryLocalFonts()-Methode zu sammeln (siehe auch die Local Font Access API).

magnetometer Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, Informationen über die Ausrichtung des Geräts über die Magnetometer-Schnittstelle zu sammeln.

microphone Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, Audioeingabegeräte zu verwenden. Wenn diese Richtlinie deaktiviert ist, wird das von MediaDevices.getUserMedia() zurückgegebene Promise mit einem NotAllowedError DOMException abgelehnt.

midi Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, die Web MIDI API zu verwenden. Wenn diese Richtlinie deaktiviert ist, wird das von Navigator.requestMIDIAccess() zurückgegebene Promise mit einem SecurityError DOMException abgelehnt.

on-device-speech-recognition Experimentell

Steuert den Zugriff auf die On-Device-Speech-Recognition-Funktionalität der Web Speech API.

otp-credentials Experimentell

Steuert, ob dem aktuellen Dokument die Nutzung der WebOTP API erlaubt ist, um ein Einmalpasswort (OTP) aus einer speziell formatierten SMS-Nachricht anzufordern, die vom Server der App gesendet wird, z. B. über navigator.credentials.get({otp: ..., ...}).

payment Experimentell

Steuert, ob dem aktuellen Dokument die Nutzung der Payment Request API erlaubt ist. Wenn diese Richtlinie aktiviert ist, löst der PaymentRequest()-Konstruktor einen SecurityError DOMException aus.

picture-in-picture Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, ein Video über die entsprechende API im Bild-in-Bild-Modus abzuspielen.

publickey-credentials-create Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, die Web Authentication API zu verwenden, um neue asymmetrische Schlüsselanmeldeinformationen zu erstellen, z. B. über navigator.credentials.create({publicKey: ..., ...}).

publickey-credentials-get Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, die Web Authentication API zu verwenden, um bereits gespeicherte öffentliche Schlüsselanmeldeinformationen abzurufen, z. B. über navigator.credentials.get({publicKey: ..., ...}).

screen-wake-lock Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, die Screen Wake Lock API zu verwenden, um anzuzeigen, dass das Gerät den Bildschirm nicht ausschalten oder dimmen sollte.

serial Experimentell

Steuert, ob dem aktuellen Dokument die Nutzung der Web Serial API erlaubt ist, um mit seriellen Geräten zu kommunizieren, die entweder direkt über einen seriellen Anschluss oder über USB- oder Bluetooth-Geräte, die einen seriellen Anschluss emulieren, angeschlossen sind.

speaker-selection Experimentell

Steuert, ob dem aktuellen Dokument die Nutzung der Audio Output Devices API zum Auflisten und Auswählen von Lautsprechern erlaubt ist.

storage-access Experimentell

Steuert, ob einem Dokument, das in einem Drittanbieter-Kontext geladen wird (d.h. eingebettet in ein <iframe>), die Nutzung der Storage Access API erlaubt ist, um Zugriff auf nicht partitionierte Cookies zu beantragen.

translator Experimentell

Steuert den Zugriff auf die Übersetzungsfunktionalität der Translator and Language Detector APIs.

summarizer Experimentell

Steuert den Zugriff auf die Summarizer API.

usb Experimentell

Steuert, ob dem aktuellen Dokument die Nutzung der WebUSB API erlaubt ist.

web-share Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, die Navigator.share() der Web Share API zu verwenden, um Text, Links, Bilder und andere Inhalte an beliebige Ziele zu übermitteln, die der Benutzer wählt, z. B. mobile Apps.

window-management Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, die Window Management API zu verwenden, um Fenster auf mehreren Bildschirmen zu verwalten.

xr-spatial-tracking Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, die WebXR Device API zu verwenden, um mit einer WebXR-Sitzung zu interagieren.

Beispiele

Grundlegende Verwendung

Permissions-Policy-Header

Um allen Ursprüngen Zugang zur Geolokalisierung zu gewähren, könnten Sie Folgendes tun:

Permissions-Policy: geolocation=*

Oder um den Zugang auf eine Teilmenge von Ursprüngen zu erlauben, könnten Sie Folgendes tun:

Permissions-Policy: geolocation=(self "https://a.example.com" "https://b.example.com")

Mehrere Funktionen können gleichzeitig gesteuert werden, indem man den Header mit einer durch Kommas getrennten Liste von Richtlinien sendet oder indem man für jede Richtlinie einen separaten Header sendet.

Zum Beispiel sind die folgenden gleichwertig:

Permissions-Policy: picture-in-picture=(), geolocation=(self https://example.com/), camera=*

Permissions-Policy: picture-in-picture=()
Permissions-Policy: geolocation=(self https://example.com/)
Permissions-Policy: camera=*

iframes

Damit ein <iframe> eine Funktion aktiviert hat, muss sein zugelassener Ursprung auch in der Allowlist für die übergeordnete Seite sein. Aufgrund dieses Vererbungsverhaltens ist es eine gute Idee, die größtmögliche Unterstützung für eine Funktion im HTTP-Header zu spezifizieren und dann die Teilmenge der Unterstützung anzugeben, die Sie in jedem <iframe> benötigen.

Um allen Ursprüngen Zugang zur Geolokalisierung zu gewähren, könnten Sie Folgendes tun:

<iframe src="https://example.com" allow="geolocation *"></iframe>

Um eine Richtlinie auf den aktuellen Ursprung und andere anzuwenden, könnten Sie Folgendes tun:

<iframe
  src="https://example.com"
  allow="geolocation 'self' https://a.example.com https://b.example.com"></iframe>

Dies ist wichtig: Standardmäßig wird die Richtlinie nicht auf den Ursprung angewendet, zu dem das <iframe> navigiert, wenn ein <iframe> zu einem anderen Ursprung navigiert. Durch die Auflistung des Ursprungs, zu dem das <iframe> navigiert, im allow-Attribut, wird die ursprünglich auf das <iframe> angewendete Berechtigungsrichtlinie auf den Ursprung angewendet, zu dem das <iframe> navigiert.

Mehrere Funktionen können gleichzeitig gesteuert werden, indem eine durch Semikolons getrennte Liste von Richtlinien-Direktiven innerhalb des allow-Attributs eingeschlossen wird.

<iframe
  src="https://example.com"
  allow="geolocation 'self' https://a.example.com https://b.example.com; fullscreen 'none'"></iframe>

Es ist erwähnenswert, den src-Wert besonders hervorzuheben. Wir haben oben erwähnt, dass die Verwendung dieses Allowlist-Werts bedeutet, dass die zugeordnete Funktion in diesem <iframe> erlaubt wird, solange das darin geladene Dokument vom selben Ursprung stammt wie die URL in seinem src-Attribut. Dieser Wert ist der default allowlist-Wert für im allow aufgelistete Funktionen, daher sind die folgenden gleichwertig:

<iframe src="https://example.com" allow="geolocation 'src'">
  <iframe src="https://example.com" allow="geolocation"></iframe
></iframe>

Den Zugriff auf leistungsstarke Funktionen verweigern

SecureCorp Inc. möchte die Mikrofon- (z. B. MediaDevices.getUserMedia()) und Geolocation-APIs in ihrer Anwendung deaktivieren. Dies kann mit folgendem Antwort-Header erfolgen:

Permissions-Policy: microphone=(), geolocation=()

Durch das Angeben von () für die Ursprungs-Liste werden die angegebenen Funktionen für alle Browsing-Kontexte (einschließlich aller <iframe>s) unabhängig von ihrem Ursprung deaktiviert.

Kombination von HTTP-Header und <iframe>-Richtlinien

Nehmen wir an, wir möchten die Nutzung der Geolokalisierung auf unserem eigenen Ursprung und in eingebetteten Inhalten unseres vertrauenswürdigen Werbenetzwerks ermöglichen. Wir könnten die seitenweite Berechtigungsrichtlinie wie folgt einrichten:

Permissions-Policy: geolocation=(self https://trusted-ad-network.com)

In unseren Werbe-<iframe>s könnten wir den Zugriff auf den Ursprung https://trusted-ad-network.com wie folgt einstellen:

<iframe src="https://trusted-ad-network.com" allow="geolocation"></iframe>

Wenn ein anderer Ursprung im <iframe> geladen wird, hätte er keinen Zugriff auf die Geolokalisierung:

<iframe src="https://rogue-origin-example.com" allow="geolocation"></iframe>

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Berechtigungsrichtlinie
• Document.featurePolicy und FeaturePolicy
• Content-Security-Policy
• Referrer-Policy