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 Permissions-Policy
Response-Header bietet einen Mechanismus, um die Nutzung von Browser-Funktionen in einem Dokument oder innerhalb von <iframe>
-Elementen im Dokument zu erlauben oder zu verweigern.
Weitere Informationen finden Sie im Hauptartikel zur Permissions Policy.
Header-Typ | Response-Header |
---|---|
Verbotener Header-Name | ja |
Syntax
Permissions-Policy: <directive>=<allowlist>
<directive>
-
Die Permissions Policy-Direktive, auf die die
allowlist
angewendet werden soll. Siehe Direktiven unten 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, getrennt durch Leerzeichen:
*
(Wildcard)-
Die Funktion ist in diesem Dokument und allen verschachtelten Browsing-Kontexten (
<iframe>
s) unabhängig von ihrem Ursprung erlaubt. ()
(leere Allowlist)-
Die Funktion ist in oberen und verschachtelten Browsing-Kontexten deaktiviert. Das Äquivalent für
<iframe>
-allow
-Attribute ist'none'
. self
-
Die Funktion ist 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 Kurzform fürhttps://your-site.example.com
betrachtet werden. Das Äquivalent für<iframe>
-allow
-Attribute istself
. src
-
Die Funktion ist 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 spezifische 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 sind.
Die Werte
*
und()
dürfen nur alleine verwendet werden, währendself
undsrc
in Kombination mit einem oder mehreren Ursprüngen verwendet werden dürfen.Hinweis: Direktiven haben eine Standard-Allowlist, die immer eine der Optionen
*
,self
odernone
für denPermissions-Policy
HTTP-Header ist und das Standardverhalten bestimmt, wenn sie nicht explizit in einer Richtlinie aufgelistet sind. Diese sind auf den einzelnen Direktiven-Referenzseiten angegeben. Für<iframe>
-allow
-Attribute ist das Standardverhalten immersrc
.
Wenn unterstützt, können Sie Platzhalter in Permissions Policy Ursprüngen einschließen. Das bedeutet, dass Sie anstelle von mehreren verschiedenen Subdomänen in einer Allowlist, alle auf einmal in einem einzigen Ursprung mit einem Platzhalter spezifizieren können.
Anstatt also
("https://example.com" "https://a.example.com" "https://b.example.com" "https://c.example.com")
Können Sie dies spezifizieren
("https://example.com" "https://*.example.com")
Hinweis: "https://*.example.com"
stimmt nicht überein mit "https://example.com"
.
Direktiven
accelerometer
Experimentell-
Kontrolliert, ob das aktuelle Dokument Informationen über die Beschleunigung des Geräts über die
Accelerometer
-Schnittstelle sammeln darf. ambient-light-sensor
Experimentell-
Kontrolliert, ob das aktuelle Dokument Informationen über die Lichtmenge in der Umgebung des Geräts über die
AmbientLightSensor
-Schnittstelle sammeln darf. attribution-reporting
Experimentell-
Kontrolliert, ob das aktuelle Dokument die Attribution Reporting API verwenden darf.
autoplay
Experimentell-
Kontrolliert, ob das aktuelle Dokument Medien automatisch abspielen darf, die über die
HTMLMediaElement
-Schnittstelle angefordert werden. Wenn diese Richtlinie deaktiviert ist und es keine Benutzerinteraktionen gab, wird das vonHTMLMediaElement.play()
zurückgegebenePromise
mit einemNotAllowedError
DOMException
abgelehnt. Das Autoplay-Attribut bei<audio>
und<video>
-Elementen wird ignoriert. bluetooth
Experimentell-
Kontrolliert, ob die Verwendung der Web Bluetooth API erlaubt ist. Wenn diese Richtlinie deaktiviert ist, geben 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-
Kontrolliert den Zugriff auf die Topics API. Wenn eine Richtlinie die Verwendung der Topics API ausdrücklich verbietet, wird jeder Versuch, die
Document.browsingTopics()
-Methode aufzurufen oder eine Anfrage mit einemSec-Browsing-Topics
-Header zu senden, mit einemNotAllowedError
DOMException
scheitern. camera
Experimentell-
Kontrolliert, ob das aktuelle Dokument Eingabegeräte für Video verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das von
getUserMedia()
zurückgegebenePromise
mit einemNotAllowedError
DOMException
abgelehnt. compute-pressure
Experimentell-
Kontrolliert den Zugriff auf die Compute Pressure API.
cross-origin-isolated
Experimentell-
Kontrolliert, ob das aktuelle Dokument als Cross-Origin Isolated behandelt werden kann.
display-capture
Experimentell-
Kontrolliert, ob das aktuelle Dokument die
getDisplayMedia()
-Methode verwenden darf, um Bildschirm-Inhalte zu erfassen. Wenn diese Richtlinie deaktiviert ist, wird das vongetDisplayMedia()
zurückgegebene Promise mit einemNotAllowedError
DOMException
abgelehnt, wenn keine Berechtigung zur Erfassung der Bildschirminhalte erteilt wird. document-domain
Experimentell-
Kontrolliert, ob das aktuelle Dokument
document.domain
setzen darf. Wenn diese Richtlinie deaktiviert ist, wird ein Versuch,document.domain
zu setzen, fehlschlagen und einenSecurityError
DOMException
auslösen. encrypted-media
Experimentell-
Kontrolliert, ob das aktuelle Dokument die Encrypted Media Extensions API (EME) verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das von
Navigator.requestMediaKeySystemAccess()
zurückgegebenePromise
mit einemSecurityError
DOMException
abgelehnt. fullscreen
Experimentell-
Kontrolliert, ob das aktuelle Dokument
Element.requestFullscreen()
verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das zurückgegebenePromise
mit einemTypeError
abgelehnt. gamepad
Experimentell-
Kontrolliert, ob das aktuelle Dokument die Gamepad API verwenden darf. Wenn diese Richtlinie deaktiviert ist, werfen Aufrufe von
Navigator.getGamepads()
einenSecurityError
DOMException
, und diegamepadconnected
undgamepaddisconnected
Ereignisse werden nicht ausgelöst. geolocation
Experimentell-
Kontrolliert, ob das aktuelle Dokument die
Geolocation
-Schnittstelle verwenden darf. Wenn diese Richtlinie deaktiviert ist, verursachen Aufrufe vongetCurrentPosition()
undwatchPosition()
, dass die Rückrufe dieser Funktionen mit einemGeolocationPositionError
CodePERMISSION_DENIED
aufgerufen werden. gyroscope
Experimentell-
Kontrolliert, ob das aktuelle Dokument Informationen über die Orientierung des Geräts über die
Gyroscope
-Schnittstelle sammeln darf. hid
Experimentell-
Kontrolliert, ob das aktuelle Dokument die WebHID API verwenden darf, um eine Verbindung zu seltenen oder exotischen Eingabegeräten wie alternativen Keyboards oder Gamepads herzustellen.
identity-credentials-get
Experimentell-
Kontrolliert, ob das aktuelle Dokument die Federated Credential Management API (FedCM) verwenden darf, insbesondere die
navigator.credentials.get()
-Methode mit eineridentity
-Option. Wenn diese Richtlinie die Verwendung der API verbietet, wird das von derget()
-Aufruf zurückgegebenePromise
mit einemNotAllowedError
DOMException
abgelehnt. idle-detection
Experimentell-
Kontrolliert, ob das aktuelle Dokument die Idle Detection API verwenden darf, um zu erkennen, wann Benutzer mit ihren Geräten interagieren. Dies kann z.B. genutzt werden, um den Status "verfügbar"/"abwesend" in Chat-Anwendungen zu melden.
local-fonts
Experimentell-
Kontrolliert, ob das aktuelle Dokument Daten zu den lokal installierten Schriften des Benutzers über die
Window.queryLocalFonts()
-Methode sammeln darf (siehe auch die Local Font Access API). magnetometer
Experimentell-
Kontrolliert, ob das aktuelle Dokument Informationen über die Orientierung des Geräts über die
Magnetometer
-Schnittstelle sammeln darf. microphone
Experimentell-
Kontrolliert, ob das aktuelle Dokument Audioeingabegeräte verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das von
MediaDevices.getUserMedia()
zurückgegebenePromise
mit einemNotAllowedError
DOMException
abgelehnt. midi
Experimentell-
Kontrolliert, ob das aktuelle Dokument die Web MIDI API verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das von
Navigator.requestMIDIAccess()
zurückgegebenePromise
mit einemSecurityError
DOMException
abgelehnt. otp-credentials
Experimentell-
Kontrolliert, ob das aktuelle Dokument die WebOTP API verwenden darf, um ein Einmalkennwort (OTP) aus einer speziell formatierten SMS-Nachricht abzurufen, die vom Server der App gesendet wird, d.h. über
navigator.credentials.get({otp: ..., ...})
. payment
Experimentell-
Kontrolliert, 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-
Kontrolliert, ob das aktuelle Dokument ein Video im Bild-in-Bild-Modus über die entsprechende API abspielen darf.
publickey-credentials-create
Experimentell-
Kontrolliert, ob das aktuelle Dokument die Web Authentication API verwenden darf, um neue asymmetrische Schlüsselanmeldedaten zu erstellen, d.h. über
navigator.credentials.create({publicKey: ..., ...})
. publickey-credentials-get
Experimentell-
Kontrolliert, ob das aktuelle Dokument die Web Authentication API verwenden darf, um bereits gespeicherte Public-Key-Anmeldedaten abzurufen, d.h. über
navigator.credentials.get({publicKey: ..., ...})
. screen-wake-lock
Experimentell-
Kontrolliert, ob das aktuelle Dokument die Screen Wake Lock API verwenden darf, um anzugeben, dass das Gerät den Bildschirm nicht ausschalten oder dimmen sollte.
serial
Experimentell-
Kontrolliert, ob das aktuelle Dokument die Web Serial API verwenden darf, um mit seriellen Geräten zu kommunizieren, entweder direkt verbunden über einen seriellen Anschluss oder über USB- oder Bluetooth-Geräte, die einen seriellen Anschluss emulieren.
speaker-selection
Experimentell-
Kontrolliert, ob das aktuelle Dokument die Audio Output Devices API verwenden darf, um Lautsprecher aufzulisten und auszuwählen.
storage-access
Experimentell-
Kontrolliert, ob ein in einem Drittanbieterkontext geladenes Dokument (d.h. eingebettet in einem
<iframe>
) die Storage Access API verwenden darf, um Zugriff auf nicht partitionierte Cookies zu beantragen. usb
Experimentell-
Kontrolliert, ob das aktuelle Dokument die WebUSB API verwenden darf.
-
Kontrolliert, 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. Mobil-Apps. window-management
Experimentell-
Kontrolliert, ob das aktuelle Dokument die Window Management API verwenden darf, um Fenster auf mehreren Bildschirmen zu verwalten.
xr-spatial-tracking
Experimentell-
Kontrolliert, 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 Zugriff auf Geolokalisierung zu erlauben, können Sie dies tun:
Permissions-Policy: geolocation=*
Oder um Zugriff auf eine Untergruppe von Ursprüngen zu erlauben, würden Sie dies 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 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
Für ein <iframe>
, das eine Funktion aktiviert haben soll, muss auch sein erlaubter Ursprung in der Allowlist der übergeordneten Seite sein. Aufgrund dieses Vererbungseffekts ist es eine gute Idee, die umfangreichste unterstützbare Unterstützung für eine Funktion im HTTP-Header anzugeben und dann die erforderliche Teilmenge der Unterstützung in jedem <iframe>
zu spezifizieren.
Um allen Ursprüngen Zugriff auf Geolokalisierung zu erlauben, 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 gilt eine Richtlinie nicht für den Ursprung, auf den das <iframe>
navigiert, wenn ein <iframe>
zu einem anderen Ursprung navigiert. Durch das Auflisten des Ursprungs, 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 Semikolons getrennte Liste von Richtlinien-Direktiven im allow
-Attribut enthalten ist.
<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 durch die Verwendung dieses Allowlist-Werts die zugehörige Funktion in diesem <iframe>
erlaubt wird, solange das darin geladene Dokument vom gleichen Ursprung wie die URL in seinem src-Attribut stammt. Dieser Wert ist der Standardallowlist
-Wert für Funktionen, die im allow
-Attribut aufgelistet sind, also sind die folgenden äquivalent:
<iframe src="https://example.com" allow="geolocation 'src'">
<iframe src="https://example.com" allow="geolocation"></iframe
></iframe>
Zugriff auf leistungsstarke Funktionen verwehren
SecureCorp Inc. möchte die Mikrofon- (zum Beispiel MediaDevices.getUserMedia()
) und Geolocation
-APIs in ihrer Anwendung deaktivieren. Dies kann so mit dem folgenden Response-Header erfolgen:
Permissions-Policy: microphone=(), geolocation=()
Durch die Angabe von ()
für die Ursprungsliste werden die angegebenen Funktionen für alle Browsing-Kontexte (einschließlich aller <iframe>
s), unabhängig von ihrem Ursprung, deaktiviert.
Kombination von HTTP-Header und <iframe>
-Richtlinien
Nehmen wir zum Beispiel an, wir möchten die Nutzung der Geolocation auf unserem eigenen Ursprung und in eingebetteten Inhalten unseres vertrauten Anzeigenetzwerks aktivieren. Wir könnten die seitenweite 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
wie folgt einrichten:
<iframe src="https://trusted-ad-network.com" allow="geolocation"></iframe>
Wenn ein anderer Ursprung im <iframe>
geladen wird, hätte er keinen Zugriff auf die 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