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

http
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>-Attribut allow 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ür https://your-site.example.com betrachtet werden. Das Äquivalent für <iframe>-Attribut allow ist self.
  • 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>-Attribut allow verwendet und ist der Standard 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 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ährend self und src in Kombination mit einem oder mehreren Ursprüngen verwendet werden können.

Hinweis: Direktiven haben eine Standard-Allowlist, die immer eine der Optionen *, self oder none für den Permissions-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 immer src.

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

http
("https://example.com" "https://a.example.com" "https://b.example.com" "https://c.example.com")

können Sie angeben

http
("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 das Promise, das von HTMLMediaElement.play() zurückgegeben wird, mit einem NotAllowedError 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 von Navigator.bluetooth zurückgegeben wird, entweder false zurückgeben oder das zurückgegebene Promise mit einem SecurityError 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 einem Sec-Browsing-Topics-Header zu senden, mit einem NotAllowedError DOMException fehlschlagen.

camera

Steuert, ob das aktuelle Dokument Videogeräte verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das Promise, das von getUserMedia() zurückgegeben wird, mit einem NotAllowedError 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 von getDisplayMedia() zurückgegebene Promise mit einem NotAllowedError 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 eine SecurityError 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 von Navigator.requestMediaKeySystemAccess() zurückgegeben wird, mit einem SecurityError DOMException abgelehnt.

fullscreen

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

gamepad Experimentell

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

geolocation

Steuert, ob das aktuelle Dokument die Geolocation Schnittstelle verwenden darf. Wenn diese Richtlinie deaktiviert ist, führen Aufrufe von getCurrentPosition() und watchPosition() dazu, dass die Rückrufe dieser Funktionen mit einem GeolocationPositionError-Code von PERMISSION_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 einer identity-Option. Wenn diese Richtlinie die Verwendung der API untersagt, wird das Promise, das vom get()-Aufruf zurückgegeben wird, mit einem NotAllowedError 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 von MediaDevices.getUserMedia() zurückgegeben wird, mit einem NotAllowedError DOMException abgelehnt.

midi Experimentell

Steuert, ob das aktuelle Dokument die Web MIDI API verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das Promise, das von Navigator.requestMIDIAccess() zurückgegeben wird, mit einem SecurityError 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() eine SecurityError 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.

web-share

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:

http
Permissions-Policy: geolocation=*

Oder um den Zugriff auf eine Teilmenge von Ursprüngen zu erlauben, würden Sie folgendes tun:

http
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:

http
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:

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

Um eine Richtlinie auf den aktuellen Ursprung und andere anzuwenden, würden Sie folgendes tun:

html
<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.

html
<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:

html
<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:

http
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:

http
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:

html
<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:

html
<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

Siehe auch