Permissions-Policy header

Syntax

Permissions-Policy: <directive>=<allowlist>

<directive>

Die Permissions Policy-Direktive, auf die die Allowlist angewendet werden soll. Eine Liste der erlaubten Direktivennamen finden Sie unter Direktiven unten.

<allowlist>

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

* (Wildcard)

Die Funktion wird in diesem Dokument und in allen verschachtelten Browsing-Kontexten (<iframe>s) unabhängig von ihrem Ursprung erlaubt.

() (leere Allowlist)

Die Funktion ist in Ober- und untergeordneten Browsing-Kontexten deaktiviert. Das Äquivalent zu <iframe>-Attributen allow ist 'none'.

self

Die Funktion wird in diesem Dokument und in allen verschachtelten Browsing-Kontexten (<iframe>s) nur im gleichen Ursprung erlaubt. Die Funktion ist in cross-origin Dokumenten in verschachtelten Browsing-Kontexten nicht erlaubt. self kann als Kurzform für https://your-site.example.com betrachtet werden. Das Äquivalent zu <iframe>-Attributen allow ist self.

src

Die Funktion wird in diesem <iframe> erlaubt, solange das darin geladene Dokument aus demselben Ursprung wie die URL in seinem src-Attribut kommt. Dieser Wert wird nur im <iframe>-Attribut allow verwendet und ist der default Allowlist-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>-Attributen nicht in Anführungszeichen gesetzt werden.

Die Werte * und () dürfen nur einzeln verwendet werden, während self und src in Kombination mit einem oder mehreren Ursprüngen verwendet werden dürfen.

Hinweis: Direktiven haben eine standardmäßige Allowlist, die immer einer der Werte *, self oder none für den Permissions-Policy HTTP-Header ist und das Standardverhalten bestimmt, wenn sie in einer Richtlinie nicht explizit aufgeführt sind. Diese sind auf den individuellen Direktiven-Referenzseiten spezifiziert. Für <iframe>-Attribute ist das Standardverhalten immer src.

Wo unterstützt, können Sie Wildcards in Permissions Policy-Ursprüngen einfügen. Dies bedeutet, dass Sie anstelle mehrerer explizit angegebener 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")

Direktiven

accelerometer Experimentell

Kontrolliert, ob das aktuelle Dokument durch die Accelerometer-Schnittstelle Informationen über die Beschleunigung des Geräts sammeln darf.

ambient-light-sensor Experimentell

Kontrolliert, ob das aktuelle Dokument durch die AmbientLightSensor-Schnittstelle Informationen über die Umgebungshelligkeit des Geräts sammeln darf.

aria-notify Experimentell

Kontrolliert, ob das aktuelle Dokument die Methode ariaNotify() verwenden darf, um Screen Reader Ankündigungen auszulösen.

attribution-reporting Veraltet

Kontrolliert, ob das aktuelle Dokument die Attribution Reporting API verwenden darf.

autoplay Experimentell

Kontrolliert, ob das aktuelle Dokument Medien-Inhalte, die über die HTMLMediaElement-Schnittstelle angefordert werden, automatisch abspielen darf. Wenn diese Richtlinie deaktiviert ist und keine Benutzerinteraktionen erfolgten, wird der von HTMLMediaElement.play() zurückgegebene Promise mit einem NotAllowedError DOMException zurückweisen. Das Autoplay-Attribut in <audio>- und <video>-Elementen wird ignoriert.

bluetooth Experimentell

Kontrolliert, ob die Nutzung der Web Bluetooth API erlaubt ist. Wenn diese Richtlinie deaktiviert ist, geben die Methoden des Bluetooth-Objekts, das von Navigator.bluetooth zurückgegeben wird, entweder false zurück oder lehnen den zurückgegebenen Promise mit einem SecurityError DOMException ab.

browsing-topics Veraltet Nicht standardisiert

Kontrolliert den Zugriff auf die Topics API. Wenn eine Richtlinie die Nutzung der Topics API spezifisch unzulässig macht, schlagen alle Versuche, die Methode Document.browsingTopics() aufzurufen oder eine Anfrage mit einem Sec-Browsing-Topics-Header zu senden, mit einem NotAllowedError DOMException fehl.

camera Experimentell

Kontrolliert, ob das aktuelle Dokument Video-Eingabegeräte verwenden darf. Der von getUserMedia() zurückgegebene Promise wird mit einem NotAllowedError DOMException zurückgewiesen, wenn die Berechtigung nicht erteilt wird.

captured-surface-control Experimentell

Kontrolliert, ob das Dokument die Captured Surface Control API nutzen darf. Das von den Hauptmethoden der API zurückgegebene Promise wird mit einem NotAllowedError DOMException zurückgewiesen, wenn die Berechtigung nicht erteilt wird.

ch-ua-high-entropy-values Experimentell

Kontrolliert, ob das Dokument die Methode NavigatorUAData.getHighEntropyValues() verwenden darf, um hochentropische User-Agent-Daten abzurufen. Wenn die Berechtigung nicht erteilt wird, gibt die Methode nur die niedrig entropischen Daten brands, mobile und platform zurück.

compute-pressure Experimentell

Kontrolliert den Zugriff auf die Compute Pressure API.

cross-origin-isolated Experimentell

Kontrolliert, ob das aktuelle Dokument als cross-origin isoliert behandelt werden kann.

deferred-fetch Experimentell

Kontrolliert die Zuweisung des fetchLater() Kontingents des obersten Ursprungs.

deferred-fetch-minimal Experimentell

Kontrolliert die Zuweisung des gemeinsamen, cross-origin Subframe fetchLater() Kontingents.

display-capture Experimentell

Kontrolliert, ob das aktuelle Dokument die Methode getDisplayMedia() verwenden darf, um Bildschirminhalte zu erfassen. Wenn diese Richtlinie deaktiviert ist, wird das von getDisplayMedia() zurückgegebene Promise mit einem NotAllowedError DOMException zurückgewiesen, wenn keine Berechtigung zur Erfassung der Anzeigedaten erhalten wird.

encrypted-media Experimentell

Kontrolliert, ob das aktuelle Dokument die Encrypted Media Extensions API (EME) verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird der von Navigator.requestMediaKeySystemAccess() zurückgegebene Promise mit einem SecurityError DOMException zurückgewiesen.

fullscreen Experimentell

Kontrolliert, ob das aktuelle Dokument Element.requestFullscreen() verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das zurückgegebene Promise mit einem TypeError zurückgewiesen.

gamepad Experimentell

Kontrolliert, ob das aktuelle Dokument die Gamepad API verwenden darf. Wenn diese Richtlinie deaktiviert ist, werden Aufrufe von Navigator.getGamepads() einen SecurityError DOMException auslösen und die Ereignisse gamepadconnected und gamepaddisconnected werden nicht ausgelöst.

geolocation Experimentell

Kontrolliert, ob das aktuelle Dokument die Geolocation Schnittstelle verwenden darf. Wenn diese Richtlinie deaktiviert ist, bewirken Aufrufe von getCurrentPosition() und watchPosition(), dass die Rückrufe dieser Funktionen mit einem GeolocationPositionError Code von PERMISSION_DENIED aufgerufen werden.

gyroscope Experimentell

Kontrolliert, ob das aktuelle Dokument Informationen über die Ausrichtung des Geräts durch die Gyroscope Schnittstelle sammeln darf.

hid Experimentell

Kontrolliert, ob das aktuelle Dokument die WebHID API verwenden darf, um sich mit ungewöhnlichen oder exotischen Mensch-Maschine-Schnittstellengeräten wie alternativen Tastaturen oder Gamepads zu verbinden.

identity-credentials-get Experimentell

Kontrolliert, ob das aktuelle Dokument die Federated Credential Management API (FedCM) verwenden darf.

idle-detection Experimentell

Kontrolliert, ob das aktuelle Dokument die Idle Detection API verwenden darf, um zu erkennen, wann Benutzer mit ihren Geräten interagieren, zum Beispiel um in Chat-Anwendungen einen "verfügbar"/"abwesend"-Status zu melden.

language-detector Experimentell

Kontrolliert den Zugriff auf die Sprachenerkennungsfunktionalität der Translator and Language Detector APIs.

local-fonts Experimentell

Kontrolliert, ob das aktuelle Dokument Daten über die lokal installierten Schriftarten des Benutzers über die Methode Window.queryLocalFonts() (siehe auch die Local Font Access API) sammeln darf.

magnetometer Experimentell

Kontrolliert, ob das aktuelle Dokument Informationen über die Ausrichtung des Geräts durch die Magnetometer Schnittstelle sammeln darf.

microphone Experimentell

Kontrolliert, ob das aktuelle Dokument Audio-Eingabegeräte verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird der von MediaDevices.getUserMedia() zurückgegebene Promise mit einem NotAllowedError DOMException zurückgewiesen.

midi Experimentell

Kontrolliert, ob das aktuelle Dokument die Web MIDI API verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird der von Navigator.requestMIDIAccess() zurückgegebene Promise mit einem SecurityError DOMException zurückgewiesen.

on-device-speech-recognition Experimentell

Kontrolliert den Zugriff auf die On-Device-Spracherkennung Funktionalität der Web Speech API.

otp-credentials Experimentell

Kontrolliert, ob das aktuelle Dokument die WebOTP API verwenden darf, um ein Einmalpasswort (OTP) aus einer speziell formatierten SMS-Nachricht anzufordern, die vom Server der App gesendet wird, z.B. ü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 Konstruktor PaymentRequest() einen SecurityError DOMException auslösen.

picture-in-picture Experimentell

Kontrolliert, ob das aktuelle Dokument ein Video im Picture-in-Picture-Modus über die entsprechende API abspielen darf.

private-state-token-issuance Experimentell

Kontrolliert die Nutzung von Private State Token token-request-Operationen.

private-state-token-redemption Experimentell

Kontrolliert die Nutzung von Private State Token token-redemption und send-redemption-record-Operationen.

publickey-credentials-create Experimentell

Kontrolliert, 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

Kontrolliert, ob das aktuelle Dokument die Web Authentication API verwenden darf, um bereits gespeicherte Anmeldeinformationen für öffentliche Schlüssel 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 anzuzeigen, dass das Gerät den Bildschirm nicht ausschalten oder abdunkeln soll.

serial Experimentell

Kontrolliert, ob das aktuelle Dokument die Web Serial API verwenden darf, um mit seriellen Geräten zu kommunizieren, entweder direkt via einem seriellen Port oder über USB- oder Bluetooth-Geräte, die einen seriellen Port 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 Drittanbieter-Kontext geladenes Dokument (d.h. eingebettet in einem <iframe>) die Storage Access API verwenden darf, um Zugriff auf unpartitionierte Cookies zu beantragen.

translator Experimentell

Kontrolliert den Zugriff auf die Übersetzungsfunktionalität der Translator and Language Detector APIs.

summarizer Experimentell

Kontrolliert den Zugriff auf die Summarizer API.

usb Experimentell

Kontrolliert, ob das aktuelle Dokument die WebUSB API verwenden darf.

web-share Experimentell

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. mobile 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 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 Zugang auf eine Teilmenge von Ursprüngen zu beschränken, 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 kommagetrennten 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

Damit eine Funktion in einem <iframe> aktiviert ist, muss auch das erlaubte Ursprung in der Allowlist der übergeordneten Seite sein. Aufgrund dieses Vererbungseffekts ist es eine gute Idee, die weitest akzeptable Unterstützung für eine Funktion im HTTP-Header anzugeben und dann das erforderliche Unterstützungsspektrum in jedem <iframe> zu spezifizieren.

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 eine Richtlinie nicht auf den Ursprung angewendet, zu dem ein <iframe> navigiert, wenn es zu einem anderen Ursprung navigiert. Indem der Ursprung, zu dem das <iframe> navigiert, im allow-Attribut aufgeführt ist, wird die auf das ursprüngliche <iframe> angewendete Permissions Policy auch auf den Ursprung angewendet, zu dem das <iframe> navigiert.

Mehrere Funktionen können gleichzeitig gesteuert werden, indem eine durch Semikolon getrennte Liste von Richtliniendirektiven im allow-Attribut enthalten ist.

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

Ein besonderer Hinweis gilt dem src-Wert. 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 geladen Dokument aus demselben Ursprung wie die URL im src-Attribut stammt. Dieser Wert ist der default Allowlist-Wert für Funktionen, die in allow aufgeführt sind, so dass die folgenden äquivalent sind:

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

Zugang zu leistungsstarken Funktionen verweigern

SecureCorp Inc. möchte die APIs für Mikrofon (zum Beispiel MediaDevices.getUserMedia()) und Geolocation in ihrer Anwendung deaktivieren. Dies kann mit folgendem Antwort-Header erfolgen:

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

Durch Angabe von () für die Ursprungsliste werden die angegebenen Funktionen für alle Browsing-Kontexte (einschließlich aller <iframe>s) deaktiviert, unabhängig von ihrem Ursprung.

Kombination von HTTP-Header- und <iframe>-Richtlinien

Angenommen, wir möchten die Nutzung der Geolokalisierungsfunktion auf unserem eigenen Ursprung und in eingebetteten Inhalten, die von unserem vertrauenswürdigen Werbenetzwerk stammen, aktivieren. Wir könnten die seitweite Permissions Policy so 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 wie folgt einrichten:

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

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

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Permissions Policy
• Document.featurePolicy und FeaturePolicy
• Content-Security-Policy
• Referrer-Policy