Permissions-Policy header

Syntax

Permissions-Policy: <directive>=<allowlist>

<directive>

Die Permissions Policy-Direktive, auf die die allowlist angewendet werden soll. Siehe Directives unten für eine Liste der erlaubten Direktivnamen.

<allowlist>

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

* (Wildcard)

Die Funktion wird in diesem Dokument und 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 in ursprungsübergreifenden Dokumenten in verschachtelten 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 Standardallowlist-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 gesetzt werden.

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

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

Wo unterstützt, können Sie Platzhalter in Permissions Policy-Ursprüngen verwenden. Dies bedeutet, dass anstelle der expliziten Angabe mehrerer verschiedener Subdomains in einer Allowlist, Sie sie alle in einem einzigen Ursprung mit einem Platzhalter angeben können.

Stattdessen 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

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 Informationen über die Lichtverhältnisse in der Umgebung des Geräts über die AmbientLightSensor-Schnittstelle sammeln darf.

aria-notify Experimentell Nicht standardisiert

Steuert, ob das aktuelle Dokument die ariaNotify()-Methode verwenden darf, um Screenreader-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 werden, automatisch wiedergegeben werden dürfen. Wenn diese Richtlinie deaktiviert ist und es keine Benutzeraktionen gab, 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 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. Wenn eine Richtlinie die Verwendung der Topics API ausdrücklich verbietet, schlagen alle Versuchsanfragen an die Methode Document.browsingTopics() oder das Senden einer Anfrage mit einem Sec-Browsing-Topics-Header mit einem NotAllowedError DOMException fehl.

camera Experimentell

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

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 ist.

ch-ua-high-entropy-values Experimentell

Steuert, ob das Dokument die Methode NavigatorUAData.getHighEntropyValues() verwenden darf, um hochgradige Benutzeragentdaten abzurufen. Wenn die Erlaubnis nicht erteilt wird, gibt die Methode nur die brands, mobile und platform niedrig entropische Daten zurück.

compute-pressure Experimentell

Steuert den Zugriff auf die Compute Pressure API.

cross-origin-isolated Experimentell

Steuert, ob das aktuelle Dokument als Cross-Origin Isolation behandelt werden kann.

deferred-fetch Experimentell

Steuert die Zuweisung des fetchLater() Kontingents des Ursprungs auf oberster Ebene.

deferred-fetch-minimal Experimentell

Steuert die Zuweisung des geteilten ursprungsübergreifenden Unterrahmenkontingents fetchLater().

display-capture Experimentell

Steuert, ob das aktuelle Dokument die Methode getDisplayMedia() verwenden darf, um Bildschirm-Inhalte zu erfassen. Wenn diese Richtlinie deaktiviert ist, wird das von getDisplayMedia() zurückgegebene Versprechen mit einem NotAllowedError DOMException abgelehnt, wenn die Erlaubnis nicht erteilt ist, den Bildschirm zu erfassen.

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, schlagen Aufrufe von Navigator.getGamepads() mit einem SecurityError DOMException fehl, und die Ereignisse gamepadconnected sowie gamepaddisconnected 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ückrufe dieser Funktionen 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 unüblichen oder exotischen Mensch-Maschine-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 Benutzer mit ihren Geräten interagieren, beispielsweise um den Status "verfügbar"/"abwesend" in Chat-Anwendungen zu melden.

language-detector Experimentell

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

local-fonts Experimentell

Steuert, ob das aktuelle Dokument Daten über die lokal installierten Schriftarten des Benutzers über die Methode Window.queryLocalFonts() 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 Audioeingabegerä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 auf dem Gerät stattfindende Sprachenerkennung der Web Speech API.

otp-credentials Experimentell

Steuert, ob das aktuelle Dokument die WebOTP API verwenden darf, um ein Einmalkennwort (OTP) von einer speziell formatierten SMS-Nachricht anzufordern, die vom Server der App gesendet wird, d.h. über navigator.credentials.get({otp: ..., ...}).

payment Experimentell

Steuert, ob das aktuelle Dokument die Payment Request API verwenden darf. Wenn diese Richtlinie aktiviert ist, löst der PaymentRequest()-Konstruktor einen SecurityError DOMException aus.

picture-in-picture Experimentell

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

private-state-token-issuance Experimentell

Steuert die Verwendung von Privater Token token-request Operationen.

private-state-token-redemption Experimentell

Steuert die Verwendung von Privater Token token-redemption und send-redemption-record Operationen.

publickey-credentials-create Experimentell

Steuert, ob das aktuelle Dokument die Web Authentication API verwenden kann, um neue asymmetrische Schlüsselanmeldeinformationen zu erstellen, d.h. über navigator.credentials.create({publicKey: ..., ...}).

publickey-credentials-get Experimentell

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

screen-wake-lock Experimentell

Steuert, ob das aktuelle Dokument die Screen Wake Lock API verwenden darf, um anzugeben, 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 Anschluss oder über USB- oder Bluetooth-Geräte, die einen seriellen Anschluss 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 ein Dokument, das in einem Drittanbieter-Kontext geladen wird (d.h. eingebettet in ein <iframe>), die Storage Access API verwenden darf, um Zugriff auf unpartitionierte Cookies anzufordern.

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 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 Benutzers 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 den Zugriff auf Geolocation zu erlauben, würden Sie Folgendes tun:

Permissions-Policy: geolocation=*

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

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

Mehrere Funktionen können gleichzeitig durch das Senden des Headers mit einer kommagetrennten Liste von Richtlinien oder durch das Senden eines separaten Headers für jede Richtlinie gesteuert werden.

Beispielsweise sind folgende Beispiele 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

Für ein <iframe>, um eine Funktion aktiviert zu haben, muss auch der erlaubte Ursprung in der Allowlist für die übergeordnete Seite vorhanden sein. Aufgrund dieses Vererbungverhaltens ist es eine gute Idee, die breiteste akzeptable Unterstützung für eine Funktion im HTTP-Header zu spezifizieren und dann die Teilmenge der Unterstützung, die Sie in jedem <iframe> benötigen.

Um allen Ursprüngen den Zugriff auf Geolocation zu erlauben, würden Sie Folgendes tun:

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

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

Mehrere Funktionen können gleichzeitig gesteuert werden, indem eine durch Semikolon getrennte Liste von Richtliniendirektiven im allow-Attribut angegeben 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 zu erwähnen. Wir haben oben erwähnt, dass die Verwendung dieses Allowlist-Wertes bedeuten wird, dass die zugeordnete Funktion in diesem <iframe> erlaubt wird, solange das darin geladene Dokument vom selben Ursprung stammt wie die URL im src-Attribut. Dieser Wert ist der Standardallowlist-Wert für Funktionen, 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>

Zugriff auf leistungsstarke Funktionen verweigern

SecureCorp Inc. möchte die Mikrofon- (z.B. MediaDevices.getUserMedia()) und Geolocation-APIs in seiner Anwendung deaktivieren. Das kann mithilfe des folgenden Antwortheaders erreicht werden:

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

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

Kombination von HTTP-Header und <iframe>-Richtlinien

Nehmen wir zum Beispiel an, dass wir die Nutzung von Geolocation auf unserem eigenen Ursprung und in eingebetteten Inhalten unseres vertrauenswürdigen Ad-Netzwerks ermöglichen wollten. Wir könnten die seitenweite Permissions Policy folgendermaßen einrichten:

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

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

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

Wenn ein anderer Ursprung schließlich in das <iframe> geladen wird, hätte es keinen Zugriff auf Geolocation:

<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