Permissions-Policy
Der HTTP-Header Permissions-Policy
bietet einen Mechanismus, um die Verwendung von Browserfunktionen in einem Dokument oder innerhalb von <iframe>
-Elementen im Dokument zu erlauben oder zu verweigern.
Weitere Informationen finden Sie im Hauptartikel über die Permissions Policy.
Header-Typ | Antwort-Header |
---|---|
Verbotener Header-Name | ja |
Syntax
Permissions-Policy: <directive>=<allowlist>
<directive>
-
Die Permissions Policy-Direktive, auf die die
allowlist
angewendet werden soll. Siehe unten Directives für eine Liste der erlaubten Direktivnamen. <allowlist>
-
Eine Allowlist ist eine Liste von Ursprüngen, die einen oder mehrere der folgenden Werte in Klammern enthält, durch Leerzeichen getrennt:
*
: Die Funktion wird in diesem Dokument und in allen eingebetteten Browsing-Kontexten (<iframe>
s) unabhängig von ihrem Ursprung erlaubt.()
(leere Allowlist): Die Funktion ist in übergeordneten und eingebetteten Browsing-Kontexten deaktiviert. Das Äquivalent für<iframe>
-Attributallow
ist'none'
.self
: Die Funktion wird in diesem Dokument und in allen eingebetteten Browsing-Kontexten (<iframe>
s) nur im gleichen Ursprung erlaubt. Die Funktion ist in cross-origin-Dokumenten in eingebetteten Browsing-Kontexten nicht erlaubt.self
kann als Abkürzung fürhttps://your-site.example.com
betrachtet werden. Das Äquivalent für<iframe>
-Attributallow
istself
.src
: Die Funktion wird in diesem<iframe>
erlaubt, solange das Dokument, das geladen wird, aus dem gleichen Ursprung wie die URL in seinem src-Attribut stammt. Dieser Wert wird nur im<iframe>
-Attributallow
verwendet und ist der Standardallowlist
-Wert in<iframe>
s."<origin>"
: Die Funktion ist für spezifische Ursprünge erlaubt (zum Beispiel"https://a.example.com"
). Ursprünge sollten durch Leerzeichen getrennt sein. Beachten Sie, dass Ursprünge in<iframe>
-Allow-Attributen nicht in Anführungszeichen gesetzt werden.
Die Werte
*
und()
können nur allein 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 Optionen
*
,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 Direktiv-Referenzseiten angegeben. Für<iframe>
-Allow-Attribute ist das Standardverhalten immersrc
.
Wo unterstützt, können Sie Wildcards in Permissions Policy-Ursprüngen einschließen. Dies bedeutet, dass Sie anstelle der expliziten Angabe mehrerer verschiedener Subdomains in einer Allowlist, alle in einem einzigen Ursprung mit einem Wildcard angeben können.
Anstatt also
("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-
Steuert, ob das aktuelle Dokument Informationen über die Beschleunigung des Geräts über das Interface
Accelerometer
sammeln darf. ambient-light-sensor
Experimentell-
Steuert, ob das aktuelle Dokument Informationen über die Lichtmenge in der Umgebung des Geräts über das Interface
AmbientLightSensor
sammeln darf. attribution-reporting
Experimentell-
Steuert, ob das aktuelle Dokument die Attribution Reporting API verwenden darf.
autoplay
Experimentell-
Steuert, ob das aktuelle Dokument Medien, die über das Interface
HTMLMediaElement
angefordert wurden, automatisch abspielen darf. Wenn diese Richtlinie deaktiviert ist und keine Benutzeraktion stattgefunden hat, wird dasPromise
, das vonHTMLMediaElement.play()
zurückgegeben wird, mit einemNotAllowedError
DOMException
abgelehnt. Das autoplay-Attribut bei<audio>
und<video>
Elementen wird ignoriert. bluetooth
Experimentell-
Steuert, ob die Verwendung der Web Bluetooth API erlaubt ist. Wenn diese Richtlinie deaktiviert ist, werden die Methoden des
Bluetooth
-Objekts, das vonNavigator.bluetooth
zurückgegeben wird, entwederfalse
zurückgeben oder das zurückgegebenePromise
mit einemSecurityError
DOMException
ablehnen. browsing-topics
Experimentell Nicht standardisiert-
Steuert den Zugriff auf die Topics API. Wenn eine Richtlinie die Verwendung der Topics API ausdrücklich untersagt, werden alle Versuche, die Methode
Document.browsingTopics()
aufzurufen oder eine Anfrage mit einemSec-Browsing-Topics
-Header zu senden, mit einemNotAllowedError
DOMException
fehlschlagen. camera
-
Steuert, ob das aktuelle Dokument Videogeräte verwenden darf. 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.
display-capture
-
Steuert, ob das aktuelle Dokument die Methode
getDisplayMedia()
verwenden darf, um Bildschirminhalte zu erfassen. Wenn diese Richtlinie deaktiviert ist, wird das vongetDisplayMedia()
zurückgegebene Promise mit einemNotAllowedError
DOMException
abgelehnt, wenn keine Erlaubnis zum Erfassen der Bildschirm Inhalte erteilt wurde. document-domain
Experimentell-
Steuert, ob das aktuelle Dokument
document.domain
setzen darf. Wenn diese Richtlinie deaktiviert ist, wird ein Versuch,document.domain
zu setzen, fehlschlagen und eineSecurityError
DOMException
wird ausgelöst. encrypted-media
Experimentell-
Steuert, ob das aktuelle Dokument die Encrypted Media Extensions API (EME) verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das
Promise
, das vonNavigator.requestMediaKeySystemAccess()
zurückgegeben wird, mit einemSecurityError
DOMException
abgelehnt. fullscreen
-
Steuert, ob das aktuelle Dokument
Element.requestFullscreen()
verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das zurückgegebenePromise
mit einemTypeError
abgelehnt. gamepad
Experimentell-
Steuert, ob das aktuelle Dokument die Gamepad API verwenden darf. Wenn diese Richtlinie deaktiviert ist, werfen Aufrufe von
Navigator.getGamepads()
eineSecurityError
DOMException
, und die Ereignissegamepadconnected
undgamepaddisconnected
werden nicht ausgelöst. geolocation
-
Steuert, ob das aktuelle Dokument die
Geolocation
Schnittstelle verwenden darf. Wenn diese Richtlinie deaktiviert ist, führen Aufrufe vongetCurrentPosition()
undwatchPosition()
dazu, dass die Rückrufe dieser Funktionen mit einemGeolocationPositionError
-Code vonPERMISSION_DENIED
aufgerufen werden. gyroscope
Experimentell-
Steuert, ob das aktuelle Dokument Informationen über die Ausrichtung des Geräts über das
Gyroscope
Interface sammeln darf. hid
Experimentell-
Steuert, ob das aktuelle Dokument die WebHID API verwenden darf, um eine Verbindung zu seltenen oder exotischen Mensch-Computer-Schnittstellengeräten wie alternativen Tastaturen oder Gamepads herzustellen.
identity-credentials-get
Experimentell-
Steuert, ob das aktuelle Dokument die Federated Credential Management API (FedCM) verwenden darf, insbesondere die Methode
navigator.credentials.get()
mit eineridentity
-Option. Wenn diese Richtlinie die Verwendung der API untersagt, wird dasPromise
, das vomget()
-Aufruf zurückgegeben wird, mit einemNotAllowedError
DOMException
abgelehnt. 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 "verfügbar"/"abwesend"-Status in Chat-Anwendungen zu melden.
local-fonts
Experimentell-
Steuert, 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-
Steuert, ob das aktuelle Dokument Informationen über die Ausrichtung des Geräts über das
Magnetometer
Interface sammeln darf. microphone
-
Steuert, ob das aktuelle Dokument Audiogeräte verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das
Promise
, das vonMediaDevices.getUserMedia()
zurückgegeben wird, mit einemNotAllowedError
DOMException
abgelehnt. midi
Experimentell-
Steuert, ob das aktuelle Dokument die Web MIDI API verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das
Promise
, das vonNavigator.requestMIDIAccess()
zurückgegeben wird, mit einemSecurityError
DOMException
abgelehnt. otp-credentials
Experimentell-
Steuert, ob das aktuelle Dokument die WebOTP API verwenden darf, um ein einmaliges Passwort (OTP) aus 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, wird der Konstruktor
PaymentRequest()
eineSecurityError
DOMException
auslösen. picture-in-picture
Experimentell-
Steuert, ob das aktuelle Dokument ein Video im Bild-in-Bild-Modus über die entsprechende API abspielen darf.
publickey-credentials-create
Experimentell-
Steuert, 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
-
Steuert, 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
-
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 Kommunikation mit seriellen Geräten aufzunehmen, 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 in einem Drittanbieter-Kontext geladenes Dokument (d.h. eingebettet in ein
<iframe>
) die Storage Access API verwenden darf, um Zugriff auf nicht partitionierte Cookies anzufordern. usb
Experimentell-
Steuert, ob das aktuelle Dokument die WebUSB API verwenden darf.
-
Steuert, ob das aktuelle Dokument
Navigator.share()
von der Web Share API verwenden darf, um Text, Links, Bilder und andere Inhalte an beliebige Ziele Ihrer Wahl zu teilen, z.B. mobile Apps. window-management
Experimentell-
Steuert, ob das aktuelle Dokument die Window Management API verwenden darf, um Fenster auf mehreren Anzeigen 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 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 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
Damit ein <iframe>
eine Funktion aktiviert hat, muss sein erlaubter Ursprung auch in der Allowlist für die übergeordnete Seite enthalten 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 erforderlichen Unterstützung in jedem <iframe>
zu spezifizieren.
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, zu dem das <iframe>
navigiert. Indem Sie den Ursprung angeben, 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 Funktionen können gleichzeitig gesteuert werden, indem eine durch Semikolon getrennte Liste von Richtlinien-Direktiven innerhalb des allow
-Attributs aufgenommen 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 speziell zu erwähnen. Wir haben oben erwähnt, dass die Verwendung dieses Allowlist-Wertes bedeutet, dass die zugehörige Funktion in diesem <iframe>
erlaubt wird, solange das Dokument, das darin geladen wird, aus demselben 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, also sind die folgenden gleichwertig:
<iframe src="https://example.com" allow="geolocation 'src'">
<iframe src="https://example.com" allow="geolocation"></iframe
></iframe>
Zugriff auf leistungsstarke Funktionen verweigern
SecureCorp Inc. möchte die APIs für Mikrofon (zum Beispiel MediaDevices.getUserMedia()
) und Geolocation
in seiner Anwendung deaktivieren. Sie können dies tun, indem Sie den folgenden Antwort-Header verwenden:
Permissions-Policy: microphone=(), geolocation=()
Indem ()
für die Ursprungs-Liste angegeben wird, werden die angegebenen Funktionen für alle Browsing-Kontexte (dies schließt alle <iframe>
s ein) deaktiviert, unabhängig von ihrem Ursprung.
Kombinieren von HTTP-Header- und <iframe>
-Richtlinien
Zum Beispiel, sagen wir, dass wir die Nutzung der Geolocation auf unserem eigenen Ursprung und in eingebetteten Inhalten, die von unserem vertrauenswürdigen Anzeigen-Netzwerk stammen, aktivieren möchten. Wir könnten die seitweitige Permissions-Policy so einrichten:
Permissions-Policy: geolocation=(self https://trusted-ad-network.com)
In unseren Anzeigen-<iframe>
s könnten wir den Zugriff auf den Ursprung https://trusted-ad-network.com
so festlegen:
<iframe src="https://trusted-ad-network.com" allow="geolocation"></iframe>
Wenn ein anderer Ursprung in <iframe>
geladen wird, hätte er keinen Zugriff auf Geolocation:
<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