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
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ürhttps://your-site.example.com
betrachtet werden. Das Äquivalent für<iframe>
allow
-Attribute istself
. 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ährendself
undsrc
in Kombination mit einem oder mehreren Ursprüngen verwendet werden können.Hinweis: Direktiven haben eine Standard-
allowlist
, die immer eine der*
,self
odernone
für denPermissions-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 immersrc
.
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:
("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")
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 vonHTMLMediaElement.play()
zurückgegebenePromise
mit einemNotAllowedError
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 vonNavigator.bluetooth
zurückgegeben wird, entwederfalse
zurück oder lehnen das zurückgegebenePromise
mit einemSecurityError
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 einemSec-Browsing-Topics
-Header zu senden, mit einemNotAllowedError
DOMException
fehl. camera
Experimentell-
Steuert, ob dem aktuellen Dokument gestattet ist, Videoeingabegeräte zu verwenden. Wenn diese Richtlinie deaktiviert ist, wird das
Promise
, das vongetUserMedia()
zurückgegeben wird, mit einemNotAllowedError
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 vongetDisplayMedia()
zurückgegeben wird, mit einemNotAllowedError
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 vonNavigator.requestMediaKeySystemAccess()
zurückgegeben wird, mit einemSecurityError
DOMException
abgelehnt. fullscreen
Experimentell-
Steuert, ob dem aktuellen Dokument gestattet wird,
Element.requestFullscreen()
zu verwenden. Wenn diese Richtlinie deaktiviert ist, wird das zurückgegebenePromise
mit einemTypeError
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 einemSecurityError
DOMException
, und die Ereignissegamepadconnected
undgamepaddisconnected
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 vongetCurrentPosition()
undwatchPosition()
dazu, dass die Callback-Funktionen dieser Funktionen mit einemGeolocationPositionError
-Code vonPERMISSION_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 eineridentity
-Option. Wenn diese Richtlinie die Nutzung der API verbietet, wird das von derget()
-Methode zurückgegebenePromise
mit einemNotAllowedError
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 vonMediaDevices.getUserMedia()
zurückgegeben wird, mit einemNotAllowedError
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 vonNavigator.requestMIDIAccess()
zurückgegeben wird, mit einemSecurityError
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()
einenSecurityError
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.
-
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:
Permissions-Policy: geolocation=*
Oder um den Zugriff auf eine Teilmenge von Ursprüngen zu gewähren, 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 kommagetrennten Liste von Richtlinien gesendet wird oder 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 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:
<iframe src="https://example.com" allow="geolocation *"></iframe>
Um eine Richtlinie für 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: 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.
<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:
<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:
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:
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:
<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:
<iframe src="https://rogue-origin-example.com" allow="geolocation"></iframe>
Spezifikationen
Specification |
---|
Permissions Policy # permissions-policy-http-header-field |