Permissions-Policy header

Syntax

Permissions-Policy: <directive>=<allowlist>

<directive>

Die Permissions-Policy-Direktive, auf die die allowlist angewandt werden soll. Siehe unten Direktiven für eine Liste der zulässigen Direktivnamen.

<allowlist>

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

* (Wildcard)

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

() (leere Allowlist)

Die Funktion ist in obersten und geschachtelten Browsing-Kontexten deaktiviert. Das Äquivalent für <iframe>-allow-Attribute ist 'none'.

self

Die Funktion wird in diesem Dokument und in allen geschachtelten Browsing-Kontexten (<iframe>s) mit demselben Ursprung erlaubt. Die Funktion ist in Fremd-Ursprung-Dokumenten in geschachtelten Browsing-Kontexten nicht erlaubt. self kann als Kurzform für https://your-site.example.com betrachtet werden. Das Äquivalent für <iframe>-allow-Attribute ist self.

src

Die Funktion wird in diesem <iframe> erlaubt, solange das hinein geladene Dokument aus demselben Ursprung stammt wie die URL in seinem src-Attribut. Dieser Wert wird nur im <iframe>-allow-Attribut 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 werden. Beachten Sie, dass Ursprünge in <iframe>-allow-Attributen nicht in Anführungszeichen stehen.

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

Hinweis: Direktiven haben eine Standard-allowlist, die immer eine von *, 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 Direktivreferenzseiten spezifiziert. Für <iframe>-allow-Attribute ist das Standardverhalten immer src.

Wo unterstützt, können Sie Platzhalter in Permissions-Policy-Ursprüngen verwenden. Dies bedeutet, dass Sie nicht mehrere verschiedene Subdomains explizit in einer Allowlist angeben müssen, sondern alle in einem einzelnen 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 spezifizieren:

("https://example.com" "https://*.example.com")

Direktiven

accelerometer Experimentell

Steuert, ob das aktuelle Dokument Informationen über die Beschleunigung des Geräts über das Accelerometer-Interface sammeln darf.

ambient-light-sensor Experimentell

Steuert, ob das aktuelle Dokument Informationen über die Lichtmenge in der Umgebung des Geräts über das AmbientLightSensor-Interface sammeln darf.

aria-notify Experimentell

Steuert, ob das aktuelle Dokument die ariaNotify()-Methode verwenden darf, um Screenreader-Ankündigungen auszulösen.

attribution-reporting Veraltet

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

autoplay Experimentell

Steuert, ob das aktuelle Dokument Medien automatisch abspielen darf, welche über das HTMLMediaElement-Interface angefordert werden. Wenn diese Richtlinie deaktiviert ist und keine Nutzerinteraktionen stattgefunden haben, wird das von HTMLMediaElement.play() zurückgegebene Promise mit einem NotAllowedError-DOMException zurückgewiesen. Das Autoplay-Attribut bei <audio> und <video>-Elementen wird ignoriert.

bluetooth Experimentell

Steuert, ob die Nutzung 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 zurückweisen.

browsing-topics Veraltet Nicht standardisiert

Steuert den Zugriff auf die Topics API. Wo 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 Experimentell

Steuert, ob das aktuelle Dokument Videoeingabegeräte verwenden darf. Das von getUserMedia() zurückgegebene Promise wird mit einem NotAllowedError-DOMException zurückgewiesen, wenn die Berechtigung nicht erlaubt ist.

captured-surface-control Experimentell

Steuert, ob das Dokument die Captured Surface Control API verwenden darf. Das von den Hauptmethoden der API zurückgegebene Promise wird mit einem NotAllowedError-DOMException zurückgewiesen, wenn die Berechtigung nicht erlaubt ist.

ch-ua-high-entropy-values Experimentell

Steuert, ob das Dokument die Methode NavigatorUAData.getHighEntropyValues() verwenden darf, um hoch-Genauigkeits-Benutzeragenten-Daten abzurufen. Wenn die Berechtigung nicht erlaubt ist, wird die Methode nur die brands, mobile und platform niedrig-Genauigkeit-Daten zurückgeben.

compute-pressure Experimentell

Steuert den Zugriff auf die Compute Pressure API.

cross-origin-isolated Experimentell

Steuert, ob das aktuelle Dokument als cross-origin isolated behandelt werden kann.

deferred-fetch Experimentell

Steuert die Zuweisung des fetchLater()-Kontingents des obersten Ursprungs.

deferred-fetch-minimal Experimentell

Steuert die Zuweisung des gemeinsamen cross-origin-Unterrahmen-fetchLater()-Kontingents.

display-capture Experimentell

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 zurückgewiesen, wenn keine Erlaubnis zur Erfassung der Bildschirm-Inhalte erteilt wurde.

encrypted-media Experimentell

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

fullscreen Experimentell

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

gamepad Experimentell

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

geolocation Experimentell

Steuert, ob das aktuelle Dokument die Geolocation-Oberfläche verwenden darf. Wenn diese Richtlinie deaktiviert ist, führen Anrufe an getCurrentPosition() und watchPosition() dazu, dass die Rückruf-Funktionen 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 ungewöhnlichen oder exotischen Eingabegeräten wie alternativen Tastaturen oder Gamepads herzustellen.

identity-credentials-get Experimentell

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

idle-detection Experimentell

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

language-detector Experimentell

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

local-fonts Experimentell

Steuert, ob das aktuelle Dokument Daten über die lokal auf dem Benutzercomputer installierten Schriftarten über die Window.queryLocalFonts()-Methode 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 Experimentell

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

midi Experimentell

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

on-device-speech-recognition Experimentell

Steuert den Zugriff auf die on-device speech recognition-Funktionalität der Web Speech API.

otp-credentials Experimentell

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

picture-in-picture Experimentell

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

private-state-token-issuance Experimentell

Steuert die Nutzung von private state token-token-request-Operationen.

private-state-token-redemption Experimentell

Steuert die Nutzung von private state token-token-redemption- und send-redemption-record-Operationen.

publickey-credentials-create Experimentell

Steuert, ob das aktuelle Dokument die Web Authentication API verwenden darf, um neue asymmetrischen Schlüsselanmeldeinformationen zu erstellen, zum Beispiel über navigator.credentials.create({publicKey: ..., ...}).

publickey-credentials-get Experimentell

Steuert, ob das aktuelle Dokument die Web Authentication API verwenden darf, um bereits gespeicherte Public-Key-Anmeldeinformationen abzurufen, zum Beispiel über navigator.credentials.get({publicKey: ..., ...}).

screen-wake-lock Experimentell

Steuert, ob das aktuelle Dokument die Screen Wake Lock API verwenden darf, um anzugeben, dass das Gerät den Bildschirm nicht ausschalten oder abdunkeln soll.

serial Experimentell

Steuert, ob das aktuelle Dokument die Web Serial API verwenden darf, um mit seriellen Geräten zu kommunizieren, die entweder direkt über einen seriellen Anschluss verbunden sind 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 zu listen 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 Zugang zu nicht partitionierten Cookies anzufordern.

translator Experimentell

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

summarizer Experimentell

Steuert den Zugriff auf die Summarizer API.

usb Experimentell

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

web-share Experimentell

Steuert, ob das aktuelle Dokument die Navigator.share() der Web Share API verwenden darf, um Text, Links, Bilder und andere Inhalte an beliebige Ziele nach Wahl des Benutzers zu teilen, z.B. mobile Apps.

window-management Experimentell

Steuert, ob das aktuelle Dokument die Window Management API verwenden darf, um Fenster auf mehreren Bildschirmen 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 Nutzung

Permissions-Policy-Header

Um allen Ursprüngen Zugriff auf die Geolokalisierung zu erlauben, würden Sie dies tun:

Permissions-Policy: geolocation=*

Oder um den Zugriff auf eine Auswahl 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 kontrolliert werden, indem der Header mit einer durch Kommata getrennten Liste von Richtlinien gesendet wird, oder indem für jede Richtlinie ein separater Header gesendet wird.

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 auch der erlaubte Ursprung in der Allowlist für die übergeordnete Seite enthalten sein. Aufgrund dieses Vererbungsverhaltens ist es eine gute Idee, die weitestgehende akzeptable Unterstützung für eine Funktion im HTTP-Header anzugeben und dann die Teilmenge der Unterstützung, die Sie in jedem <iframe> benötigen, zu spezifizieren.

Um allen Ursprüngen Zugriff auf die 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>

Das 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, zu dem das <iframe> navigiert, im allow-Attribut auflisten, wird die Permissions-Policy, die auf das ursprüngliche <iframe> angewendet wurde, auch auf den Ursprung angewendet, zu dem das <iframe> navigiert.

Mehrere Funktionen können gleichzeitig kontrolliert werden, indem eine durch Semikolons 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>

Es ist wert, dem src-Wert besondere Erwähnung zu geben. Wir haben oben erwähnt, dass die Verwendung dieses Allowlist-Wertes bedeutet, dass die zugehörige Funktion in diesem <iframe> erlaubt wird, solange das hineingeladene Dokument aus demselben Ursprung stammt wie die URL in seinem src-Attribut. Dieser Wert ist der Standard allowlist-Wert für in allow aufgeführte Funktionen, daher sind die folgenden gleichwertig:

<iframe src="https://example.com" allow="geolocation 'src'"></iframe>
<iframe src="https://example.com" allow="geolocation"></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. Es kann dies mit dem folgenden Response-Header tun:

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

Indem () für die Ursprungs-Liste angegeben wird, werden die angegebenen Funktionen für alle Browsing-Kontexte deaktiviert (dies schließt alle <iframe>s ein), unabhängig von ihrem Ursprung.

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

Lassen Sie uns zum Beispiel sagen, dass wir die Nutzung der Geolokalisierung auf unserem eigenen Ursprung und in eingebetteten Inhalten von unserem vertrauenswürdigen Werbenetzwerk aktivieren möchten. Wir könnten die seitenweite Permissions-Policy so einrichten:

Permissions-Policy: geolocation=(self https://trusted-ad-network.com)

In unseren Ad-<iframe>s könnten wir den Zugriff auf den https://trusted-ad-network.com-Ursprung so einstellen:

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

Wenn ein anderer Ursprung in <iframe> geladen würde, hätte er keinen Zugriff auf Geolokalisierung:

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

Verletzungen melden

Dieses Beispiel zeigt, wie die Meldung von Verletzungen der Permissions-Policy an einen Server-Endpunkt konfiguriert wird.

Die untenstehenden Response-Header blockieren die Geolokalisierung und definieren einen "default"-Meldung-Endpunkt unter Verwendung des Reporting-Endpoints HTTP-Response-Headers. Berichte über Verletzungen der Permissions-Policy werden automatisch an diesen Endpunkt gesendet.

Reporting-Endpoints: default="https://example.com/reports"
Permissions-Policy: geolocation=()

Eine Verletzung tritt auf, wenn eine Seite versucht, die blockierte Funktion zu verwenden, zum Beispiel:

navigator.geolocation.getCurrentPosition(
  () => {},
  () => {},
);

Die an den Endpunkt gesendete Berichtsnutzlast könnte so aussehen:

[
  {
    "age": 48512,
    "body": {
      "columnNumber": 29,
      "disposition": "enforce",
      "lineNumber": 44,
      "message": "Permissions policy violation: geolocation access has been blocked because of a permissions policy applied to the current document.",
      "featureId": "geolocation",
      "sourceFile": "https://example.com/"
    },
    "type": "permissions-policy-violation",
    "url": "https://example.com/",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36"
  }
]

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Permissions Policy
• Document.featurePolicy und FeaturePolicy
• Content-Security-Policy
• Referrer-Policy
• Reporting-Endpoints
• PermissionsPolicyViolationReport
• ReportingObserver
• Reporting API