Permissions-Policy header

Syntax

Permissions-Policy: <directive>=<allowlist>

<directive>

Die Permissions Policy-Direktive, auf die die Allowlist angewendet wird. Siehe Direktiven unten für eine Liste der erlaubten Direktivnamen.

<allowlist>

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

* (Wildcard)

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

() (leere Allowlist)

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

self

Die Funktion wird in diesem Dokument und in allen verschachtelten Browsing-Kontexten (<iframe>s) im selben Ursprung erlaubt. Die Funktion ist nicht in Cross-Origin-Dokumenten in verschachtelten Browsing-Kontexten erlaubt. self kann als Kurzform 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 aus demselben Ursprung wie die URL im src-Attribut stammt. Dieser Wert wird nur im <iframe> allow Attribut verwendet und ist der Standard Allowlist-Wert in <iframe>s.

"<origin>"

Die Funktion ist für spezifische Ursprünge erlaubt (beispielsweise "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 alleine verwendet werden, während self und src in Kombination mit einem oder mehreren Ursprüngen verwendet werden können.

Hinweis: Direktiven haben eine Standard-Whitelist, die immer *, self oder none für den Permissions-Policy HTTP-Header ist und das Standardverhalten bestimmt, wenn sie nicht explizit in einer Richtlinie aufgeführt sind. Diese sind auf den einzelnen Direktivreferenzseiten 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. Dies bedeutet, dass Sie anstelle mehrerer unterschiedlicher Subdomains in einer Allowlist alle durch einen einzigen Ursprung mit einem Wildcard angeben können.

Anstelle von

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

Kontrolliert, ob das aktuelle Dokument Informationen über die Beschleunigung des Geräts über die Accelerometer Schnittstelle sammeln darf.

ambient-light-sensor Experimentell

Kontrolliert, ob das aktuelle Dokument Informationen über die Umgebungslichtmenge rund um das Gerät über die AmbientLightSensor Schnittstelle sammeln darf.

aria-notify Experimentell Nicht standardisiert

Kontrolliert, ob das aktuelle Dokument die ariaNotify() Methode verwenden darf, um Screen Reader Ankündigungen auszulösen.

attribution-reporting Veraltet

Kontrolliert, ob das aktuelle Dokument die Attribution Reporting API verwenden darf.

autoplay Experimentell

Kontrolliert, ob das aktuelle Dokument Medien, die über die HTMLMediaElement Schnittstelle angefordert werden, automatisch abspielen darf. Wenn diese Richtlinie deaktiviert ist und es keine Benutzeraktionen gab, wird das von HTMLMediaElement.play() zurückgegebene Promise mit einem NotAllowedError DOMException zurückgewiesen. Das autoplay-Attribut bei <audio>- und <video>-Elementen wird ignoriert.

bluetooth Experimentell

Kontrolliert, ob die Nutzung der Web Bluetooth API erlaubt ist. Wenn diese Richtlinie deaktiviert ist, geben die Methoden des von Navigator.bluetooth zurückgegebenen Bluetooth Objekts entweder false zurück oder lehnen das zurückgegebene Promise mit einem SecurityError DOMException ab.

browsing-topics Veraltet Nicht standardisiert

Kontrolliert den Zugriff auf die Topics API. Wo eine Richtlinie die Nutzung der Topics API ausdrücklich verbietet, wird jeder Versuch, die Document.browsingTopics() Methode aufzurufen oder eine Anfrage mit einem Sec-Browsing-Topics Header zu senden, mit einem NotAllowedError DOMException fehlschlagen.

camera Experimentell

Kontrolliert, ob das aktuelle Dokument Videoeingabegeräte verwenden darf. Das von getUserMedia() zurückgegebene Promise wird mit einem NotAllowedError DOMException abgelehnt, wenn die Berechtigung nicht erlaubt ist.

captured-surface-control Experimentell

Kontrolliert, 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 gewährt ist.

compute-pressure Experimentell

Kontrolliert den Zugriff auf die Compute Pressure API.

cross-origin-isolated Experimentell

Kontrolliert, ob das aktuelle Dokument als Cross-Origin Isolated behandelt werden kann.

deferred-fetch Experimentell

Kontrolliert die Zuteilung der fetchLater()-Quote auf oberster Ursprungebene.

deferred-fetch-minimal Experimentell

Kontrolliert die Zuteilung der gemeinsamen fetchLater()-Quote für Cross-Origin-Subframes](/de/docs/Web/API/fetchLater_API/fetchLater_quotas).

display-capture Experimentell

Kontrolliert, ob das aktuelle Dokument die Erlaubnis hat, die getDisplayMedia()-Methode zu verwenden, um Bildschirminhalte zu erfassen. Wenn diese Richtlinie deaktiviert ist, wird das von getDisplayMedia() zurückgegebene Versprechen mit einem NotAllowedError DOMException abgelehnt, wenn keine Erlaubnis zur Erfassung der Displayinhalte vorliegt.

encrypted-media Experimentell

Kontrolliert, ob das aktuelle Dokument die Encrypted Media Extensions API (EME) verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das von Navigator.requestMediaKeySystemAccess() zurückgegebene Promise mit einem SecurityError DOMException abgelehnt.

fullscreen Experimentell

Kontrolliert, ob das aktuelle Dokument Element.requestFullscreen() verwenden darf. Wenn diese Richtlinie deaktiviert ist, lehnt das zurückgegebene Promise mit einem TypeError ab.

gamepad Experimentell

Kontrolliert, ob das aktuelle Dokument die Gamepad API verwenden darf. Wenn diese Richtlinie deaktiviert ist, schlagen Aufrufe von Navigator.getGamepads() mit einem SecurityError DOMException fehl, und die gamepadconnected und gamepaddisconnected Ereignisse werden nicht ausgelöst.

geolocation Experimentell

Kontrolliert, ob das aktuelle Dokument die Geolocation Schnittstelle verwenden darf. Wenn diese Richtlinie deaktiviert ist, führen Aufrufe von getCurrentPosition() und watchPosition() dazu, dass die Rückrufe dieser Funktionen mit einem GeolocationPositionError-Code von PERMISSION_DENIED aufgerufen werden.

gyroscope Experimentell

Kontrolliert, ob das aktuelle Dokument Informationen über die Orientierung des Geräts über die Gyroscope Schnittstelle sammeln darf.

hid Experimentell

Kontrolliert, ob das aktuelle Dokument die WebHID API verwenden darf, um sich mit unüblichen oder exotischen Human Interface Devices wie alternativen Tastaturen oder Gamepads zu verbinden.

identity-credentials-get Experimentell

Kontrolliert, ob das aktuelle Dokument die Federated Credential Management API (FedCM) verwenden darf.

idle-detection Experimentell

Kontrolliert, ob das aktuelle Dokument die Idle Detection API verwenden darf, um zu erkennen, wann Benutzer mit ihren Geräten interagieren, beispielsweise um den Status "verfügbar"/"abwesend" in Chat-Anwendungen zu melden.

language-detector Experimentell

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

local-fonts Experimentell

Kontrolliert, ob das aktuelle Dokument Daten zu den lokal installierten Schriftarten des Benutzers über die Window.queryLocalFonts()-Methode sammeln darf (siehe auch die Local Font Access API).

magnetometer Experimentell

Kontrolliert, ob das aktuelle Dokument Informationen über die Orientierung des Geräts über die Magnetometer Schnittstelle sammeln darf.

microphone Experimentell

Kontrolliert, ob das aktuelle Dokument Audioeingabegeräte verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das von MediaDevices.getUserMedia() zurückgegebene Promise mit einem NotAllowedError DOMException abgelehnt.

midi Experimentell

Kontrolliert, ob das aktuelle Dokument die Web MIDI API verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das von Navigator.requestMIDIAccess() zurückgegebene Promise mit einem SecurityError DOMException abgelehnt.

on-device-speech-recognition Experimentell

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

otp-credentials Experimentell

Kontrolliert, ob das aktuelle Dokument die WebOTP API verwenden darf, 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

Kontrolliert, ob das aktuelle Dokument die Payment Request API verwenden darf. Wenn diese Richtlinie aktiviert ist, wirft der PaymentRequest()-Konstruktor einen SecurityError DOMException.

picture-in-picture Experimentell

Kontrolliert, ob das aktuelle Dokument Videos im Picture-in-Picture-Modus über die entsprechende API abspielen darf.

publickey-credentials-create Experimentell

Kontrolliert, ob das aktuelle Dokument die Web Authentication API verwenden darf, um neue asymmetrische Schlüsselanmeldeinformationen zu erstellen, z. B. über navigator.credentials.create({publicKey: ..., ...}).

publickey-credentials-get Experimentell

Kontrolliert, ob das aktuelle Dokument die Web Authentication API verwenden darf, um bereits gespeicherte Public-Key-Anmeldeinformationen abzurufen, z. B. über navigator.credentials.get({publicKey: ..., ...}).

screen-wake-lock Experimentell

Kontrolliert, ob das aktuelle Dokument die Screen Wake Lock API verwenden darf, um anzugeben, dass das Gerät den Bildschirm nicht ausschalten oder dimmen sollte.

serial Experimentell

Kontrolliert, ob das aktuelle Dokument die Web Serial API verwenden darf, um mit seriellen Geräten zu kommunizieren, sei es direkt über einen seriellen Anschluss oder über USB- oder Bluetooth-Geräte, die einen seriellen Anschluss emulieren.

speaker-selection Experimentell

Kontrolliert, ob das aktuelle Dokument die Audio Output Devices API verwenden darf, um Lautsprecher aufzulisten und auszuwählen.

storage-access Experimentell

Kontrolliert, ob ein in einem Drittanbieter-Kontext geladenes Dokument (d.h. eingebettet in ein <iframe>) die Storage Access API verwenden darf, um Zugriff auf unpartitionierte Cookies zu beantragen.

translator Experimentell

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

summarizer Experimentell

Kontrolliert den Zugriff auf die Summarizer API.

usb Experimentell

Kontrolliert, ob das aktuelle Dokument die WebUSB API verwenden darf.

web-share Experimentell

Kontrolliert, ob das aktuelle Dokument die Navigator.share() der Web Share API verwenden darf, um Text, Links, Bilder und andere Inhalte an beliebige Ziele der Wahl des Benutzers zu teilen, z. B. mobile Apps.

window-management Experimentell

Kontrolliert, ob das aktuelle Dokument die Window Management API verwenden darf, um Fenster auf mehreren Displays zu verwalten.

xr-spatial-tracking Experimentell

Kontrolliert, ob das aktuelle Dokument die WebXR Device API verwenden darf, um mit einer WebXR-Sitzung zu interagieren.

Beispiele

Grundlegende Verwendung

Permissions-Policy Header

Um allen Ursprüngen Zugang zur Geolokalisierung zu erlauben, würden Sie dies tun:

Permissions-Policy: geolocation=*

Oder um den Zugriff auf eine Teilmenge von Ursprüngen zu erlauben, würden Sie dies tun:

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

Mehrere Funktionen können gleichzeitig kontrolliert werden, indem der Header mit einer durch Kommas getrennten Liste von Richtlinien gesendet wird oder indem ein separater Header für jede Richtlinie gesendet wird.

Zum Beispiel sind die folgenden äquivalent:

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 der erlaubte Ursprung auch in der Allowlist für die übergeordnete Seite enthalten sein. Aufgrund dieses Vererbungverhaltens ist es eine gute Idee, die größte akzeptable Unterstützung für eine Funktion im HTTP-Header anzugeben und dann die Teilmenge der Unterstützung zu spezifizieren, die Sie in jedem <iframe> benötigen.

Um allen Ursprüngen Zugang zur Geolokalisierung zu erlauben, würden Sie dies tun:

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

Um eine Richtlinie auf den aktuellen Ursprung und andere anzuwenden, würden Sie dies 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, wenn ein <iframe> zu einem anderen Ursprung navigiert, nicht auf den Ursprung angewendet, zu dem das <iframe> navigiert. Indem Sie den Ursprung, zu dem das <iframe> navigiert, im allow-Attribut auflisten, wird die ursprünglich auf das <iframe> angewendete Permissions Policy auf den Ursprung angewendet, zu dem das <iframe> navigiert.

Mehrere Funktionen können gleichzeitig kontrolliert werden, indem eine durch Semikolon getrennte Liste von Richtliniendirektiven im allow-Attribut enthalten ist.

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

Es lohnt sich, den src-Wert besonders zu erwähnen. Wir erwähnten oben, dass die Verwendung dieses Allowlist-Werts bedeutet, dass die zugehörige Funktion in diesem <iframe> erlaubt wird, solange das darin geladene Dokument aus demselben Ursprung wie die URL im src-Attribut stammt. Dieser Wert ist der Default Allowlist-Wert für die in allow aufgeführten Funktionen, daher sind die folgenden äquivalent:

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

Zugriff auf leistungsstarke Funktionen verweigern

SecureCorp Inc. möchte die Mikrophone (z. B. MediaDevices.getUserMedia()) und Geolocation APIs in seiner Anwendung deaktivieren. Es kann dies mit dem folgenden Response-Header tun:

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

Indem () für die Ursprungslisté angegeben wird, werden die angegebenen Funktionen für alle Browsing-Kontexte (dies schließt alle <iframe>s ein) deaktiviert, unabhängig von ihrem Ursprung.

Kombination von HTTP-Header und <iframe>-Richtlinien

Zum Beispiel, nehmen wir an, dass wir die Verwendung der Geolokalisierung auf unserem eigenen Ursprung und in eingebetteten Inhalten, die von unserem vertrauenswürdigen Werbenetzwerk kommen, aktivieren möchten. Wir könnten die seitenweite Permissions Policy so einrichten:

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

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

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

Wenn ein anderer Ursprung in das <iframe> geladen wird, hat es kein Zugriff auf die Geolokalisierung:

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

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