Permissions-Policy header

Syntax

Permissions-Policy: <directive>=<allowlist>

<directive>

Die Permissions Policy-Direktive, auf die die Allowlist angewendet werden soll. Siehe unten unter Direktiven die Liste der erlaubten Direktivnamen.

<allowlist>

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

* (Wildcard)

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

() (leere Allowlist)

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

self

Das Feature wird in diesem Dokument und in allen verschachtelten Browsing-Kontexten (<iframe>s) erlaubt, die nur demselben Ursprung angehören. Das Feature ist in verschachtelten, ursprungsübergreifenden Dokumenten 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

Das Feature wird in diesem <iframe> erlaubt, solange das geladene Dokument vom gleichen Ursprung wie die URL in seinem src-Attribut stammt. Dieser Wert wird nur im <iframe>-allow-Attribut verwendet und ist der Standard Allowlist-Wert in <iframe>s.

"<origin>"

Das Feature 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 gesetzt sind.

Die Werte * und () dürfen nur einzeln 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 das Standardverhalten regelt, wenn sie nicht explizit in einer Richtlinie aufgeführt sind. Diese sind in den einzelnen Direktivreferenzseiten spezifiziert. Für <iframe>-allow-Attribute ist das Standardverhalten immer src.

Wo unterstützt, können Sie Wildcards in Permissions-Policy-Ursprüngen einfügen. Das bedeutet, dass Sie, anstatt mehrere verschiedene Subdomains explizit in einer Allowlist anzugeben, alle in einem einzigen Ursprung mit einem Wildcard spezifizieren können.

Also anstatt

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

Können Sie spezifizieren

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

Direktiven

accelerometer Experimentell

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

ambient-light-sensor Experimentell

Steuert, ob das aktuelle Dokument über die AmbientLightSensor-Schnittstelle Informationen über die Lichtmenge in der Umgebung des Geräts sammeln darf.

aria-notify Experimentell Nicht standardisiert

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

attribution-reporting Veraltet

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

autoplay Experimentell

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

bluetooth Experimentell

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

browsing-topics Veraltet Nicht standardisiert

Steuert den Zugriff auf die Topics API. Wo eine Richtlinie speziell die Verwendung der Topics API untersagt, 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

Steuert, ob das aktuelle Dokument Videoinputgeräte verwenden darf. Das von getUserMedia() zurückgegebene Promise wird mit einem NotAllowedError-DOMException abgelehnt, wenn die Erlaubnis nicht gegeben ist.

captured-surface-control Experimentell

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

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 Zuteilung der fetchLater()-Quote für den übergeordneten Ursprung.

deferred-fetch-minimal Experimentell

Steuert die Zuteilung der fetchLater()-Quote für subgrenzüberschreitende eingebettete Frames.

display-capture Experimentell

Steuert, ob das aktuelle Dokument die getDisplayMedia()-Methode zum Erfassen von Bildschirmansichten verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das von getDisplayMedia() zurückgegebene Versprechen mit einem NotAllowedError-DOMException abgelehnt, wenn keine Berechtigung zum Erfassen der Bildschirmansicht erteilt wurde.

encrypted-media Experimentell

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

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

gamepad Experimentell

Steuert, ob das aktuelle Dokument die Gamepad API verwenden darf. Wenn diese Richtlinie deaktiviert ist, werden Aufrufe von Navigator.getGamepads() einen SecurityError-DOMException werfen, und die gamepadconnected- und gamepaddisconnected-Ereignisse werden nicht ausgelöst.

geolocation Experimentell

Steuert, 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ückruffunktionen dieser Methoden mit einem GeolocationPositionError-Code von PERMISSION_DENIED aufgerufen werden.

gyroscope Experimentell

Steuert, ob das aktuelle Dokument Informationen über die Ausrichtung des Geräts über die Gyroscope-Schnittstelle sammeln darf.

hid Experimentell

Steuert, ob das aktuelle Dokument die WebHID API verwenden darf, um sich mit seltenen oder exotischen menschlichen Schnittstellengeräten wie alternativen Tastaturen oder Gamepads zu verbinden.

identity-credentials-get Experimentell

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

idle-detection Experimentell

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

language-detector Experimentell

Steuert den Zugriff auf die Sprachenerkennungsfunktion der Übersetzer- und Sprachenerkennungs-APIs.

local-fonts Experimentell

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

magnetometer Experimentell

Steuert, ob das aktuelle Dokument Informationen über die Ausrichtung des Geräts über die Magnetometer-Schnittstelle sammeln darf.

microphone Experimentell

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

midi Experimentell

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

Steuert den Zugriff auf die Geräteinterne Spracherkennung der Web Speech API.

otp-credentials Experimentell

Steuert, ob das aktuelle Dokument die WebOTP API verwenden darf, um ein Einmalkennwort (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 das aktuelle Dokument die Payment Request API verwenden darf. Wenn diese Richtlinie aktiv ist, wird der PaymentRequest()-Konstruktor einen SecurityError-DOMException werfen.

picture-in-picture Experimentell

Steuert, ob das aktuelle Dokument ein Video im Bild-im-Bild-Modus über die entsprechende API abspielen darf.

private-state-token-issuance Experimentell

Steuert die Verwendung von token-request-Operationen des Private State Token.

private-state-token-redemption Experimentell

Steuert die Verwendung von token-redemption- und send-redemption-record-Operationen des Private State Token.

publickey-credentials-create Experimentell

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

Steuert, ob das aktuelle Dokument die Web Authentication API verwenden darf, um bereits gespeicherte öffentliche Schlüsselanmeldeinformationen abzurufen, z.B. über navigator.credentials.get({publicKey: ..., ...}).

screen-wake-lock Experimentell

Steuert, ob das aktuelle Dokument die Screen Wake Lock API verwenden darf, um zu signalisieren, dass das Gerät den Bildschirm nicht ausschalten oder dimmen soll.

serial Experimentell

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

speaker-selection Experimentell

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

storage-access Experimentell

Steuert, ob einem in einem Drittanbieter-Kontext geladenen Dokument (z.B. in einem <iframe> eingebettet) die Verwendung der Storage Access API erlaubt ist, um Zugriff auf nicht partitionierte Cookies anzufordern.

translator Experimentell

Steuert den Zugriff auf die Übersetzungsfunktionalität der Übersetzer- und Sprachenerkennungs-APIs.

summarizer Experimentell

Steuert den Zugriff auf die Summarizer API.

usb Experimentell

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

web-share Experimentell

Steuert, 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 Nutzers zu teilen, z.B. mobile Apps.

window-management Experimentell

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

xr-spatial-tracking Experimentell

Steuert, 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 Zugriff auf Geolokalisierung zu gewähren, 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 Features können gleichzeitig gesteuert werden, indem der Header mit einer durch Kommas getrennten Liste von Richtlinien gesendet wird oder indem für jede Richtlinie ein separater Header gesendet wird.

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> ein Feature aktiviert hat, muss sein erlaubter Ursprung auch in der Allowlist für die übergeordnete Seite enthalten sein. Aufgrund dieses Vererbungverhaltens ist es ratsam, im HTTP-Header die breiteste akzeptable Unterstützung für ein Feature anzugeben und dann die Teilmenge der Unterstützung, die Sie für jedes <iframe> benötigen.

Um allen Ursprüngen Zugriff auf Geolokalisierung zu gewähren, 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 eine Richtlinie nicht auf den Ursprung angewendet, zu dem ein <iframe> navigiert, wenn es zu einem anderen Ursprung navigiert. Durch das Auflisten des Ursprungs, zu dem das <iframe> navigiert, im allow-Attribut wird die Permissions-Policy, die auf das ursprüngliche <iframe> angewendet wurde, auf den Ursprung angewendet, zu dem das <iframe> navigiert.

Mehrere Features können gleichzeitig gesteuert werden, indem eine durch Semikolons 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>

Der src-Wert verdient eine besondere Erwähnung. Wir haben oben erwähnt, dass die Verwendung dieses Allowlist-Werts bedeutet, dass das zugehörige Feature in diesem <iframe> erlaubt wird, solange das darin geladene Dokument vom gleichen Ursprung wie die URL im src-Attribut stammt. Dieser Wert ist der Standard Allowlist-Wert für Features, die in allow aufgeführt sind, daher sind die folgenden gleichwertig:

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

Verweigern des Zugriffs auf leistungsstarke Funktionen

SecureCorp Inc. möchte die Mikrofon- (zum Beispiel MediaDevices.getUserMedia()) und Geolocation-APIs in seiner Anwendung deaktivieren. Dies kann mit dem folgenden Response-Header erfolgen:

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

Durch Angabe von () für die Ursprungs-Liste werden die angegebenen Funktionen für alle Browsing-Kontexte (dies schließt alle <iframe>s ein) unabhängig von ihrem Ursprung deaktiviert.

Kombination von HTTP-Header- und <iframe>-Richtlinien

Angenommen, wir wollten die Nutzung von Geolokalisierung auf unserem eigenen Ursprung und in eingebetteten Inhalten von unserem vertrauenswürdigen Anzeigennetzwerk aktivieren. Wir könnten die seitenweite Permissions-Policy folgendermaßen einrichten:

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

In unseren Anzeigen-<iframe>s könnten wir den Zugriff auf den https://trusted-ad-network.com-Ursprung folgendermaßen festlegen:

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

Wenn ein anderer Ursprung in das <iframe> geladen wird, hätte er keinen Zugriff auf 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