Permissions-Policy header

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Der HTTP Permissions-Policy Antwort-Header bietet einen Mechanismus, um die Nutzung von Browser-Funktionen in einem Dokument oder in einem beliebigen <iframe>-Element im Dokument zu erlauben oder zu verweigern.

Weitere Informationen finden Sie im Hauptartikel zur Permissions Policy.

Art des Headers Antwort-Header
Verbotener Anforderungs-Header ja

Syntax

http
Permissions-Policy: <directive>=<allowlist>
<directive>

Die anzuwendende Permissions Policy-Direktive für die allowlist. Eine Liste der zulässigen Direktivnamen finden Sie unten unter Direktiven.

<allowlist>

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

* (Platzhalter)

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 zugelassen und in allen geschachtelten Browsing-Kontexten (<iframe>s) im gleichen Ursprung erlaubt. Die Funktion ist nicht in Ursprüngen von Drittanbietern in geschachtelten Browsing-Kontexten 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 aus dem gleichen Ursprung stammt wie die URL in ihrem src-Attribut. Dieser Wert wird nur im <iframe> allow-Attribut verwendet und ist der Standard-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 gesetzt werden.

Die Werte * und () können 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-allowlist, die immer eine der *, 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 auf den einzelnen Direktivreferenzseiten spezifiziert. Für <iframe> allow-Attribute ist das Standardverhalten immer src.

Wo unterstützt, können Sie in Permissions Policy-Ursprüngen Platzhalter verwenden. Das bedeutet, dass Sie, anstatt mehrere verschiedene Subdomains explizit anzugeben, sie alle in einem einzigen Ursprung mit einem Platzhalter spezifizieren können.

Anstelle von:

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

Können Sie angeben:

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

Hinweis: "https://*.example.com" entspricht nicht "https://example.com".

Direktiven

accelerometer Experimentell

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

ambient-light-sensor Experimentell

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

attribution-reporting Experimentell

Steuert, ob dem aktuellen Dokument gestattet ist, die Attribution Reporting API zu verwenden.

autoplay Experimentell

Steuert, ob dem aktuellen Dokument gestattet ist, Medien über die HTMLMediaElement-Schnittstelle automatisch abzuspielen. Wenn diese Richtlinie deaktiviert ist und es keine Nutzeraktionen gab, wird das von HTMLMediaElement.play() zurückgegebene Promise mit einem NotAllowedError DOMException abgelehnt. Das Autoplay-Attribut bei <audio>- und <video>-Elementen wird ignoriert.

bluetooth Experimentell

Steuert, ob die Verwendung der Web Bluetooth API gestattet ist. Wenn diese Richtlinie deaktiviert ist, liefern 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 Experimentell Nicht standardisiert

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

camera Experimentell

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

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 der fetchLater()-Quote des obersten Ursprungs.

deferred-fetch-minimal Experimentell

Steuert die Zuweisung der geteilten cross-origin Subframe fetchLater()-Quote.

display-capture Experimentell

Steuert, ob dem aktuellen Dokument erlaubt ist, die Methode getDisplayMedia() zu verwenden, um Bildschirminhalte zu erfassen. Wenn diese Richtlinie deaktiviert ist, wird das Promise, das von getDisplayMedia() zurückgegeben wird, mit einem NotAllowedError DOMException abgelehnt, falls die Erlaubnis zur Erfassung der Bildschirminhalte nicht erteilt wird.

encrypted-media Experimentell

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

fullscreen Experimentell

Steuert, ob dem aktuellen Dokument gestattet wird, 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 gestattet ist, die Gamepad API zu verwenden. Wenn diese Richtlinie deaktiviert ist, führen Aufrufe von Navigator.getGamepads() zu einem SecurityError DOMException, und die Ereignisse gamepadconnected und gamepaddisconnected werden nicht ausgelöst.

geolocation Experimentell

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

gyroscope Experimentell

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

hid Experimentell

Steuert, ob dem aktuellen Dokument gestattet ist, die WebHID API zu verwenden, um eine Verbindung zu ungewöhnlichen oder exotischen Mensch-Maschine-Schnittstellengeräten, wie Alternativ-Tastaturen oder Gamepads, herzustellen.

identity-credentials-get Experimentell

Steuert, ob dem aktuellen Dokument gestattet ist, die Federated Credential Management API (FedCM) zu verwenden, insbesondere die Methode navigator.credentials.get() mit einer identity-Option. Wenn diese Richtlinie die Nutzung der API verbietet, wird das von der get()-Methode zurückgegebene Promise mit einem NotAllowedError DOMException abgelehnt.

idle-detection Experimentell

Steuert, ob dem aktuellen Dokument gestattet ist, die Idle Detection API zu verwenden, um zu erkennen, wann Benutzer mit ihren Geräten interagieren, zum Beispiel um den "verfügbar"/"abwesend"-Status 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 dem aktuellen Dokument gestattet ist, Daten zu den lokal installierten Schriften des Benutzers über die Methode Window.queryLocalFonts() zu sammeln (siehe auch die Local Font Access API).

magnetometer Experimentell

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

microphone Experimentell

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

midi Experimentell

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

otp-credentials Experimentell

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

payment Experimentell

Steuert, ob dem aktuellen Dokument gestattet ist, die Payment Request API zu verwenden. Wenn diese Richtlinie aktiviert ist, wird der Konstruktor PaymentRequest() einen SecurityError DOMException auslösen.

picture-in-picture Experimentell

Steuert, ob dem aktuellen Dokument gestattet ist, ein Video über den entsprechenden API im Bild-im-Bild-Modus abzuspielen.

publickey-credentials-create Experimentell

Steuert, ob dem aktuellen Dokument gestattet ist, die Web Authentication API zu verwenden, um neue asymmetrische Schlüsselanmeldedaten zu erstellen, d.h. über navigator.credentials.create({publicKey: ..., ...}).

publickey-credentials-get Experimentell

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

screen-wake-lock Experimentell

Steuert, ob dem aktuellen Dokument gestattet 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 gestattet ist, die Web Serial API zu verwenden, um mit seriellen Geräten zu kommunizieren, entweder direkt über einen seriellen Anschluss verbunden oder über USB- oder Bluetooth-Geräte, die einen seriellen Anschluss emulieren.

speaker-selection Experimentell

Steuert, ob dem aktuellen Dokument gestattet ist, die Audio Output Devices API zu verwenden, um Lautsprecher aufzulisten und auszuwählen.

storage-access Experimentell

Steuert, ob einem Dokument, das in einem Drittanbieter-Kontext geladen wird (z. B. eingebettet in ein <iframe>), gestattet ist, die Storage Access API zu verwenden, 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 dem aktuellen Dokument gestattet ist, die WebUSB API zu verwenden.

web-share Experimentell

Steuert, ob dem aktuellen Dokument gestattet ist, die Navigator.share() der Web Share API zu verwenden, um Text, Links, Bilder und andere Inhalte an beliebige Ziele nach Wahl des Nutzers zu teilen, z.B. mobile Apps.

window-management Experimentell

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

xr-spatial-tracking Experimentell

Steuert, ob dem aktuellen Dokument gestattet ist, die WebXR Device API zu verwenden, 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:

http
Permissions-Policy: geolocation=*

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

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

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

Zum Beispiel sind die folgenden äquivalent:

http
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 haben kann, muss sein zulässiger Ursprung auch in der allowlist der übergeordneten Seite aufgeführt sein. Aufgrund dieses Vererbungverhaltens ist es eine gute Idee, die breiteste akzeptable Unterstützung für eine Funktion im HTTP-Header anzugeben und dann die Untermenge der Unterstützung, die Sie benötigen, in jedem <iframe> zu spezifizieren.

Um allen Ursprüngen Zugriff auf Geolokalisierung zu gewähren, würden Sie dies tun:

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

Um eine Richtlinie für den aktuellen Ursprung und andere anzuwenden, würden Sie dies tun:

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

Dies ist wichtig: Wenn ein <iframe> standardmäßig zu einem anderen Ursprung navigiert, wird die Richtlinie nicht auf den Ursprung angewendet, zu dem das <iframe> navigiert. Indem der Ursprung, zu dem das <iframe> navigiert, im allow-Attribut aufgeführt wird, wird die ursprüngliche für 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 angegeben wird.

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

Es lohnt sich, dem src-Wert eine besondere Erwähnung zu geben. Wir haben oben erwähnt, dass die Verwendung dieses allowlist-Wertes bedeutet, dass die zugehörige Funktion in diesem <iframe> erlaubt wird, solange das darin geladene Dokument aus dem gleichen Ursprung stammt wie die URL in seinem src-Attribut. Dieser Wert ist der Standard-allowlist-Wert für Funktionen, die in allow aufgelistet sind, daher sind die folgenden äquivalent:

html
<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- (zum Beispiel MediaDevices.getUserMedia()) und Geolocation APIs in seiner Anwendung deaktivieren. Dies kann mit dem folgenden Antwort-Header erreicht werden:

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

Indem () für die Ursprungs-Liste angegeben wird, werden die spezifizierten Funktionen für alle Browsing-Kontexte (einschließlich aller <iframe>s) deaktiviert, unabhängig von ihrem Ursprung.

Kombination von HTTP-Header und <iframe>-Richtlinien

Zum Beispiel, wenn wir die Nutzung von Geolokalisierung auf unserem eigenen Ursprung und in eingebetteten Inhalte von unserem vertrauenswürdigen Werbenetzwerk aktivieren möchten, könnten wir die seitenweite Permissions Policy wie folgt festlegen:

http
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 wie folgt festlegen:

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

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

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

Spezifikationen

Specification
Permissions Policy
# permissions-policy-http-header-field

Browser-Kompatibilität

Siehe auch