Permissions-Policy
Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.
Der HTTP-Header Permissions-Policy
bietet einen Mechanismus, um die Nutzung von Browser-Funktionen in einem Dokument oder innerhalb von darin enthaltenen <iframe>
-Elementen zu erlauben und zu verweigern.
Weitere Informationen finden Sie im Hauptartikel zur Permissions Policy.
Header-Typ | Antwort-Header |
---|---|
Verbotener Header-Name | ja |
Syntax
Permissions-Policy: <directive>=<allowlist>
<directive>
-
Die
Permissions Policy
-Direktive, auf die dieErlaubnisliste
angewendet werden soll. Eine Liste der zulässigen Direktivnamen finden Sie unter Directives unten. <allowlist>
-
Eine Erlaubnisliste ist eine Liste von Quellen, die einen oder mehrere der folgenden Werte in Klammern enthalten, getrennt durch Leerzeichen:
*
(Wildcard)-
Die Funktion wird in diesem Dokument und allen eingebetteten Browsing-Kontexten (
<iframe>
s) unabhängig von ihrem Ursprung erlaubt. ()
(leere Erlaubnisliste)-
Die Funktion ist in obersten und eingebetteten Browsing-Kontexten deaktiviert. Das Äquivalent für
<iframe>
allow
-Attribute ist'none'
. self
-
Die Funktion wird in diesem Dokument und in allen eingebetteten Browsing-Kontexten (
<iframe>
s) im gleichen Ursprung erlaubt. Die Funktion ist in fremden Dokumenten in eingebetteten Browsing-Kontexten nicht erlaubt.self
kann als Kurzform 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 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 spezifische Ursprünge erlaubt (z. B.
"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 allein verwendet werden, währendself
undsrc
in Kombination mit einem oder mehreren Ursprüngen verwendet werden können.Hinweis: Direktiven haben eine Standard-Erlaubnisliste, die immer entweder
*
,self
odernone
für denPermissions-Policy
HTTP-Header ist und das Standardverhalten steuert, 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 immersrc
.
Wo unterstützt, können Sie Wildcards in Permissions Policy-Ursprüngen einschließen. Das bedeutet, dass Sie anstelle mehrerer verschiedener Subdomains in einer Erlaubnisliste alle in einem einzigen Ursprung mit einer 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")
Hinweis: "https://*.example.com"
stimmt nicht mit "https://example.com"
überein.
Direktiven
accelerometer
Experimentell-
Steuerung, ob das aktuelle Dokument Informationen über die Beschleunigung des Geräts über die
Accelerometer
-Schnittstelle sammeln darf. ambient-light-sensor
Experimentell-
Steuerung, ob das aktuelle Dokument Informationen über die Umgebungshelligkeit des Geräts über die
AmbientLightSensor
-Schnittstelle sammeln darf. attribution-reporting
Experimentell-
Steuerung, ob das aktuelle Dokument die Attribution Reporting API nutzen darf.
autoplay
Experimentell-
Steuerung, ob das aktuelle Dokument Medien automatisch abspielen darf, die über die
HTMLMediaElement
-Schnittstelle angefordert werden. Wenn diese Richtlinie deaktiviert ist und keine Benutzeraktionen vorliegen, wird dasPromise
, das vonHTMLMediaElement.play()
zurückgegeben wird, mit einemNotAllowedError
DOMException
zurückgewiesen. Das autoplay-Attribut bei<audio>
- und<video>
-Elementen wird ignoriert. bluetooth
Experimentell-
Steuerung, ob die Verwendung der Web Bluetooth API erlaubt ist. Wenn diese Richtlinie deaktiviert ist, werden die Methoden des
Bluetooth
-Objekts, das durchNavigator.bluetooth
zurückgegeben wird, entwederfalse
zurückgeben oder das zurückgegebenePromise
mit einemSecurityError
DOMException
zurückweisen. browsing-topics
Experimentell Nicht standardisiert-
Steuerung des Zugriffs auf die Topics API. Wenn eine Richtlinie die Nutzung der Topics API ausdrücklich verbietet, schlagen Versuche fehl, die Methode
Document.browsingTopics()
aufzurufen oder eine Anfrage mit einemSec-Browsing-Topics
-Header zu senden, und es wird einNotAllowedError
DOMException
ausgelöst. camera
Experimentell-
Steuerung, ob das aktuelle Dokument Videoeingabegeräte verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das
Promise
, das durchgetUserMedia()
zurückgegeben wird, mit einemNotAllowedError
DOMException
zurückgewiesen. compute-pressure
Experimentell-
Steuerung des Zugriffs auf die Compute Pressure API.
display-capture
Experimentell-
Steuerung, ob das aktuelle Dokument die Methode
getDisplayMedia()
verwenden darf, um Bildschirmfelder aufzuzeichnen. Wenn diese Richtlinie deaktiviert ist, wird das durchgetDisplayMedia()
zurückgegebene Promise mit einemNotAllowedError
DOMException
zurückgewiesen, wenn keine Berechtigung zum Aufzeichnen der Bildschirminhalte erlangt wird. document-domain
Experimentell-
Steuerung, ob das aktuelle Dokument
document.domain
setzen darf. Wenn diese Richtlinie deaktiviert ist, schlägt der Versuch,document.domain
zu setzen, fehl und einSecurityError
DOMException
wird ausgelöst. encrypted-media
Experimentell-
Steuerung, ob das aktuelle Dokument die Encrypted Media Extensions API (EME) verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das
Promise
, das durchNavigator.requestMediaKeySystemAccess()
zurückgegeben wird, mit einemSecurityError
DOMException
zurückgewiesen. fullscreen
Experimentell-
Steuerung, ob das aktuelle Dokument
Element.requestFullscreen()
verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das zurückgegebenePromise
mit einemTypeError
zurückgewiesen. gamepad
Experimentell-
Steuerung, ob das aktuelle Dokument die Gamepad API verwenden darf. Wenn diese Richtlinie deaktiviert ist, werfen Aufrufe von
Navigator.getGamepads()
einenSecurityError
DOMException
, und die Ereignissegamepadconnected
undgamepaddisconnected
werden nicht ausgelöst. geolocation
Experimentell-
Steuerung, ob das aktuelle Dokument die
Geolocation
-Schnittstelle verwenden darf. Wenn diese Richtlinie deaktiviert ist, führen Aufrufe vongetCurrentPosition()
undwatchPosition()
dazu, dass die Rückruffunktion dieser Methoden mit einemGeolocationPositionError
-Code vonPERMISSION_DENIED
aufgerufen wird. gyroscope
Experimentell-
Steuerung, ob das aktuelle Dokument Informationen über die Orientierung des Geräts über die
Gyroscope
-Schnittstelle sammeln darf. hid
Experimentell-
Steuerung, ob das aktuelle Dokument die WebHID API verwenden darf, um eine Verbindung zu seltenen oder exotischen Eingabegeräten wie alternativen Tastaturen oder Gamepads herzustellen.
identity-credentials-get
Experimentell-
Steuerung, ob das aktuelle Dokument die Federated Credential Management API (FedCM) und insbesondere die Methode
navigator.credentials.get()
mit eineridentity
-Option verwenden darf. Wo diese Richtlinie die Nutzung der API verbietet, wird dasPromise
, das durch denget()
-Aufruf zurückgegeben wird, mit einemNotAllowedError
DOMException
zurückgewiesen. idle-detection
Experimentell-
Steuerung, ob das aktuelle Dokument die Idle Detection API verwenden darf, um zu erkennen, wann Benutzer mit ihren Geräten interagieren, z. B. um in Chat-Anwendungen einen "verfügbar"/"abwesend"-Status zu melden.
local-fonts
Experimentell-
Steuerung, ob das aktuelle Dokument Daten über die lokal installierten Schriften des Benutzers über die Methode
Window.queryLocalFonts()
sammeln darf (siehe auch die Local Font Access API). magnetometer
Experimentell-
Steuerung, ob das aktuelle Dokument Informationen über die Orientierung des Geräts über die
Magnetometer
-Schnittstelle sammeln darf. microphone
Experimentell-
Steuerung, ob das aktuelle Dokument Audioeingabegeräte verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das
Promise
, das durchMediaDevices.getUserMedia()
zurückgegeben wird, mit einemNotAllowedError
DOMException
zurückgewiesen. midi
Experimentell-
Steuerung, ob das aktuelle Dokument die Web MIDI API verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das
Promise
, das durchNavigator.requestMIDIAccess()
zurückgegeben wird, mit einemSecurityError
DOMException
zurückgewiesen. otp-credentials
Experimentell-
Steuerung, ob das aktuelle Dokument die WebOTP API nutzen darf, um ein Einmalkennwort (OTP) aus einer speziell formatierten SMS-Nachricht zu erfassen, die vom Server der App gesendet wird, d. h. über
navigator.credentials.get({otp: ..., ...})
. payment
Experimentell-
Steuerung, ob das aktuelle Dokument die Payment Request API verwenden darf. Wenn diese Richtlinie aktiviert ist, wird der
PaymentRequest()
-Konstruktor einenSecurityError
DOMException
auslösen. picture-in-picture
Experimentell-
Steuerung, ob das aktuelle Dokument ein Video im Bild-in-Bild-Modus über die entsprechende API abspielen darf.
publickey-credentials-create
Experimentell-
Steuerung, ob das aktuelle Dokument die Web Authentication API verwenden darf, um neue asymmetrische Schlüsselanmeldeinformationen zu erstellen, d. h. über
navigator.credentials.create({publicKey: ..., ...})
. publickey-credentials-get
Experimentell-
Steuerung, ob das aktuelle Dokument die Web Authentication API verwenden darf, um bereits gespeicherte öffentliche Schlüsselanmeldeinformationen abzurufen, d. h. über
navigator.credentials.get({publicKey: ..., ...})
. screen-wake-lock
Experimentell-
Steuerung, 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-
Steuerung, 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-
Steuerung, ob das aktuelle Dokument die Audio Output Devices API verwenden darf, um Lautsprecher aufzulisten und auszuwählen.
storage-access
Experimentell-
Steuerung, 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 nicht partitionierte Cookies anzufordern. usb
Experimentell-
Steuerung, ob das aktuelle Dokument die WebUSB API verwenden darf.
-
Steuerung, ob das aktuelle Dokument die
Navigator.share()
der Web Share API verwenden darf, um Text, Links, Bilder und andere Inhalte zu beliebigen Zielen nach Wahl des Benutzers zu teilen, z. B. mobile Apps. window-management
Experimentell-
Steuerung, ob das aktuelle Dokument die Window Management API verwenden darf, um Fenster auf mehreren Displays zu verwalten.
xr-spatial-tracking
Experimentell-
Steuerung, ob das aktuelle Dokument die WebXR Device API verwenden darf, um mit einer WebXR-Sitzung zu interagieren.
Beispiele
Grundlegende Nutzung
Permissions-Policy-Header
Um allen Ursprüngen Zugriff auf die Geolokalisierung zu gewähren, würden Sie dies tun:
Permissions-Policy: geolocation=*
Oder um den Zugriff auf einen Teil der Ursprünge 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 durch Senden des Headers mit einer durch Kommas getrennten Liste von Richtlinien oder durch Senden eines separaten Headers für jede Richtlinie gesteuert werden.
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>
eine Funktion aktiviert hat, muss der erlaubte Ursprung auch in der Erlaubnisliste für die Hauptseite enthalten sein. Aufgrund dieses Vererbung-Verhaltens ist es eine gute Idee, die breiteste akzeptable Unterstützung für eine Funktion im HTTP-Header anzugeben und dann den Unterstützungsumfang, den Sie benötigen, in jedem <iframe>
anzugeben.
Um allen Ursprüngen Zugriff auf die 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, wenn ein <iframe>
zu einem anderen Ursprung navigiert, die Richtlinie nicht auf den Ursprung angewendet, zu dem das <iframe>
navigiert. Durch das Auflisten des Ursprungs, zu dem das <iframe>
navigiert, im allow
-Attribut wird die Permissions Policy
, die ursprünglich auf das <iframe>
angewendet wurde, auch auf den Ursprung angewendet, zu dem das <iframe>
navigiert.
Mehrere Funktionen können gleichzeitig durch Einfügen einer durch Semikolon getrennten Liste von Richtliniendirektiven in das allow
-Attribut gesteuert werden.
<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 haben oben erwähnt, dass die Verwendung dieses Erlaubnislistenwerts bedeutet, dass die zugehörige Funktion in diesem <iframe>
erlaubt wird, solange das darin geladene Dokument aus dem gleichen Ursprung wie die URL in seinem src-Attribut stammt. Dieser Wert ist der Standard allowlist
Wert für Funktionen, die in allow
aufgeführt sind, sodass die folgenden gleichwertig sind:
<iframe src="https://example.com" allow="geolocation 'src'">
<iframe src="https://example.com" allow="geolocation"></iframe
></iframe>
Zugang zu leistungsstarken Funktionen verweigern
SecureCorp Inc. möchte die Mikrofon- (zum Beispiel MediaDevices.getUserMedia()
) und Geolocation
-APIs in seiner Anwendung deaktivieren. Dies kann es mit dem folgenden Antwort-Header tun:
Permissions-Policy: microphone=(), geolocation=()
Indem ()
für die Ursprungs-Liste angegeben wird, 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
Zum Beispiel, sagen wir, wir wollten die Nutzung der Geolokalisierung auf unserem eigenen Ursprung und in eingebetteten Inhalten von unserem vertrauenswürdigen Werbenetzwerk erlauben. Wir könnten die seitenweite Permissions Policy
folgendermaßen einrichten:
Permissions-Policy: geolocation=(self https://trusted-ad-network.com)
In unseren Werbe-<iframe>
s könnten wir den Zugriff auf den Ursprung https://trusted-ad-network.com
folgendermaßen einstellen:
<iframe src="https://trusted-ad-network.com" allow="geolocation"></iframe>
Wenn ein anderer Ursprung letztendlich in das <iframe>
geladen wird, hätte er keinen Zugriff auf die Geolokalisierung:
<iframe src="https://rogue-origin-example.com" allow="geolocation"></iframe>
Spezifikationen
Specification |
---|
Permissions Policy # permissions-policy-http-header-field |
Browser-Kompatibilität
BCD tables only load in the browser