Permissions-Policy header

Syntax

# Single directive
Permissions-Policy: <directive>=<allowlist>

# Single directive with reporting endpoint
Permissions-Policy: <directive>=<allowlist>;report-to=<endpoint>

# Multiple directives, with and without server reporting endpoints
Permissions-Policy: <directive>=<allowlist>, <directive>=<allowlist>;report-to=<endpoint>, ...

Mit dem Header lassen sich Allowlists für eine oder mehrere Direktiven festlegen. Optional kann für jede Direktive ein Parameter report-to angegeben werden, der den Server-Endpunkt für Berichte über Richtlinienverstöße bezeichnet. Die Einträge für die einzelnen Direktiven werden durch Kommas getrennt.

<directive>

Die Permissions-Policy-Direktive, auf die die allowlist angewendet wird. Eine Liste der zulässigen Direktivenamen finden Sie unter Direktiven.

<allowlist>

Eine Allowlist ist eine Liste von Origins. Sie enthält einen oder mehrere der folgenden Werte, die in Klammern stehen und durch Leerzeichen getrennt sind:

* (Platzhalter)

Die Funktion ist in diesem Dokument und in allen verschachtelten Browsing-Kontexten (<iframe>-Elementen) unabhängig von deren Origin erlaubt.

() (leere Allowlist)

Die Funktion ist in Browsing-Kontexten der obersten Ebene und in verschachtelten Browsing-Kontexten deaktiviert. Die Entsprechung für das allow-Attribut eines <iframe>-Elements ist 'none'.

self

Die Funktion ist in diesem Dokument und ausschließlich in verschachtelten Browsing-Kontexten (<iframe>-Elementen) derselben Origin erlaubt. In Dokumenten anderer Origins innerhalb verschachtelter Browsing-Kontexte ist sie nicht erlaubt. self kann als Kurzform für https://your-site.example.com betrachtet werden. Die Entsprechung für das allow-Attribut eines <iframe>-Elements ist self.

src

Die Funktion ist in diesem <iframe>-Element erlaubt, sofern das darin geladene Dokument dieselbe Origin hat wie die URL in seinem Attribut src. Dieser Wert wird nur im allow-Attribut eines <iframe>-Elements verwendet und ist der Standardwert für eine Funktion, für die kein ausdrücklicher Allowlist-Wert angegeben wurde. Beispielsweise ist allow="geolocation" gleichbedeutend mit allow="geolocation 'src'".

"<origin>"

Die Funktion ist für bestimmte Origins erlaubt (beispielsweise "https://a.example.com"). Origins werden durch Leerzeichen getrennt. Beachten Sie, dass Origins in allow-Attributen von <iframe>-Elementen nicht in Anführungszeichen stehen.

Die Werte * und () dürfen nur einzeln verwendet werden, während self und src mit einer oder mehreren Origins kombiniert werden können.

Hinweis: Direktiven haben eine Standard-Allowlist, die gilt, wenn die Direktive nicht ausdrücklich in einer Richtlinie aufgeführt ist. Den jeweiligen Standardwert finden Sie auf der Referenzseite der Direktive. Unter Standard-Allowlists erfahren Sie, wie dies mit dem Permissions-Policy-Header und dem allow-Attribut eines <iframe>-Elements zusammenwirkt.

report-to=<endpoint> Optional

Mit dem Parameter report-to lässt sich der Name eines Reporting-Endpunkts angeben, an den Berichte gesendet werden, wenn gegen die zugehörige Direktive verstoßen wird. Der Name des Endpunkts und die zugehörige URL müssen in einem separaten HTTP-Antwort-Header Reporting-Endpoints angegeben werden.

Wird der Parameter weggelassen, werden Berichte an den Reporting-Endpunkt default gesendet, sofern einer definiert wurde. Weitere Informationen finden Sie unter Reporting API.

Sofern unterstützt, können Sie Platzhalter in Origins einer Permissions Policy verwenden. Dadurch müssen Sie nicht mehrere unterschiedliche Subdomains einzeln in einer Allowlist angeben, sondern können sie alle mit einem Platzhalter in einer einzigen Origin erfassen.

Statt:

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

können Sie Folgendes angeben:

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

Direktiven

accelerometer

Steuert, ob das aktuelle Dokument über die Schnittstelle Accelerometer Informationen zur Beschleunigung des Geräts erfassen darf.

ambient-light-sensor

Steuert, ob das aktuelle Dokument über die Schnittstelle AmbientLightSensor Informationen zur Lichtmenge in der Umgebung des Geräts erfassen darf.

aria-notify

Steuert, ob das aktuelle Dokument mit der Methode ariaNotify() Ankündigungen für Screenreader auslösen darf.

attribution-reporting

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

autoplay

Steuert, ob das aktuelle Dokument über die Schnittstelle HTMLMediaElement angeforderte Medien automatisch abspielen darf. Wenn diese Richtlinie die Funktion deaktiviert und keine Benutzerinteraktion stattgefunden hat, wird das von HTMLMediaElement.play() zurückgegebene Promise mit einer DOMException vom Typ NotAllowedError zurückgewiesen. Das autoplay-Attribut von <audio>- und <video>-Elementen wird ignoriert.

bluetooth

Steuert, ob die Web Bluetooth API verwendet werden darf. Wenn diese Richtlinie die Funktion deaktiviert, geben die Methoden des von Navigator.bluetooth zurückgegebenen Bluetooth-Objekts entweder false zurück oder weisen das zurückgegebene Promise mit einer DOMException vom Typ SecurityError zurück.

browsing-topics

Steuert den Zugriff auf die Topics API. Wenn eine Richtlinie die Verwendung der Topics API ausdrücklich untersagt, schlagen sowohl Aufrufe der Methode Document.browsingTopics() als auch Anfragen mit einem Sec-Browsing-Topics-Header mit einer DOMException vom Typ NotAllowedError fehl.

camera

Steuert, ob das aktuelle Dokument Videoeingabegeräte verwenden darf. Wenn die Berechtigung nicht erteilt ist, wird das von getUserMedia() zurückgegebene Promise mit einer DOMException vom Typ NotAllowedError zurückgewiesen.

captured-surface-control

Steuert, ob das Dokument die Captured Surface Control API verwenden darf. Wenn die Berechtigung nicht erteilt ist, wird das von den Hauptmethoden der API zurückgegebene Promise mit einer DOMException vom Typ NotAllowedError zurückgewiesen.

ch-ua-high-entropy-values

Steuert, ob das Dokument mit der Methode NavigatorUAData.getHighEntropyValues() User-Agent-Daten mit hoher Entropie abrufen darf. Wenn die Berechtigung nicht erteilt ist, gibt die Methode nur die Daten mit niedriger Entropie brands, mobile und platform zurück.

compute-pressure

Steuert den Zugriff auf die Compute Pressure API.

cross-origin-isolated

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

deferred-fetch

Steuert die Zuweisung des fetchLater()-Kontingents der Origin auf oberster Ebene.

deferred-fetch-minimal

Steuert die Zuweisung des gemeinsam genutzten fetchLater()-Kontingents für Subframes anderer Origins.

display-capture

Steuert, ob das aktuelle Dokument mit der Methode getDisplayMedia() Bildschirminhalte erfassen darf. Wenn diese Richtlinie die Funktion deaktiviert, wird das von getDisplayMedia() zurückgegebene Promise mit einer DOMException vom Typ NotAllowedError zurückgewiesen, sofern keine Berechtigung zum Erfassen der Bildschirminhalte erteilt wird.

encrypted-media

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

fullscreen

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

gamepad

Steuert, ob das aktuelle Dokument die Gamepad API verwenden darf. Wenn diese Richtlinie die Funktion deaktiviert, lösen Aufrufe von Navigator.getGamepads() eine DOMException vom Typ SecurityError aus. Die Ereignisse gamepadconnected und gamepaddisconnected werden dann nicht ausgelöst.

geolocation

Steuert, ob das aktuelle Dokument die Schnittstelle Geolocation verwenden darf. Wenn diese Richtlinie die Funktion deaktiviert, bewirken Aufrufe von getCurrentPosition() und watchPosition(), dass die Callbacks dieser Funktionen mit dem GeolocationPositionError-Code PERMISSION_DENIED aufgerufen werden.

gyroscope

Steuert, ob das aktuelle Dokument über die Schnittstelle Gyroscope Informationen zur Ausrichtung des Geräts erfassen darf.

hid

Steuert, ob das aktuelle Dokument die WebHID API verwenden darf, um eine Verbindung zu ungewöhnlichen Human-Interface-Geräten wie alternativen Tastaturen oder Gamepads herzustellen.

identity-credentials-get

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

idle-detection

Steuert, ob das aktuelle Dokument mit der Idle Detection API erkennen darf, wann Benutzer mit ihren Geräten interagieren, beispielsweise um in Chat-Anwendungen den Status „verfügbar“ oder „abwesend“ anzuzeigen.

language-detector

Steuert den Zugriff auf die Spracherkennungsfunktionen der Translator and Language Detector APIs.

language-model

Steuert den Zugriff auf die Prompt API.

local-fonts

Steuert, ob das aktuelle Dokument mit der Methode Window.queryLocalFonts() Daten über lokal installierte Schriftarten des Benutzers erfassen darf (siehe auch die Local Font Access API).

local-network

Steuert, ob das aktuelle Dokument Netzwerkanfragen an lokale Adressen senden darf.

local-network-access

Steuert, ob das aktuelle Dokument Netzwerkanfragen an lokale und Loopback-Adressen senden darf. Diese Richtliniendirektive ist ein Alias für die spezifischeren Direktiven local-network und loopback-network.

loopback-network

Steuert, ob das aktuelle Dokument Netzwerkanfragen an Loopback-Adressen senden darf.

magnetometer

Steuert, ob das aktuelle Dokument über die Schnittstelle Magnetometer Informationen zur Ausrichtung des Geräts erfassen darf.

microphone

Steuert, ob das aktuelle Dokument Audioeingabegeräte verwenden darf. Wenn diese Richtlinie die Funktion deaktiviert, wird das von MediaDevices.getUserMedia() zurückgegebene Promise mit einer DOMException vom Typ NotAllowedError zurückgewiesen.

midi

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

on-device-speech-recognition

Steuert den Zugriff auf die Funktion zur Spracherkennung auf dem Gerät der Web Speech API.

otp-credentials

Steuert, ob das aktuelle Dokument mit der WebOTP API ein Einmalpasswort (OTP) aus einer speziell formatierten SMS anfordern darf, die vom Server der Anwendung gesendet wurde, beispielsweise über navigator.credentials.get({otp: ..., ...}).

payment

Steuert, ob das aktuelle Dokument die Payment Request API verwenden darf. Wenn diese Richtlinie aktiviert ist, löst der Konstruktor PaymentRequest() eine DOMException vom Typ SecurityError aus.

picture-in-picture

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

private-state-token-issuance

Steuert die Verwendung von token-request-Operationen für Private State Tokens.

private-state-token-redemption

Steuert die Verwendung von token-redemption- und send-redemption-record-Operationen für Private State Tokens.

publickey-credentials-create

Steuert, ob das aktuelle Dokument mit der Web Authentication API neue Anmeldedaten mit asymmetrischen Schlüsseln erstellen darf, beispielsweise über navigator.credentials.create({publicKey: ..., ...}).

publickey-credentials-get

Steuert, ob das aktuelle Dokument mit der Web Authentication API bereits gespeicherte Anmeldedaten mit öffentlichen Schlüsseln abrufen darf, beispielsweise über navigator.credentials.get({publicKey: ..., ...}).

screen-wake-lock

Steuert, ob das aktuelle Dokument mit der Screen Wake Lock API festlegen darf, dass das Gerät den Bildschirm nicht ausschaltet oder abdunkelt.

serial

Steuert, ob das aktuelle Dokument über die Web Serial API mit seriellen Geräten kommunizieren darf. Dazu zählen Geräte, die direkt über einen seriellen Anschluss verbunden sind, sowie USB- oder Bluetooth-Geräte, die einen seriellen Anschluss emulieren.

speaker-selection

Steuert, ob das aktuelle Dokument mit der Audio Output Devices API Lautsprecher auflisten und auswählen darf.

storage-access

Steuert, ob ein Dokument, das in einem Drittanbieter-Kontext geladen wurde (also in ein <iframe> eingebettet ist), mit der Storage Access API Zugriff auf nicht partitionierte Cookies anfordern darf.

translator

Steuert den Zugriff auf die Übersetzungsfunktionen der Translator and Language Detector APIs.

summarizer

Steuert den Zugriff auf die Summarizer API.

unload

Steuert, ob das aktuelle Dokument Ereignis-Handler für unload ausführen darf.

usb

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

web-share

Steuert, ob das aktuelle Dokument Navigator.share() aus der Web Share API verwenden darf, um Texte, Links, Bilder und andere Inhalte an vom Benutzer ausgewählte Ziele wie mobile Apps weiterzugeben.

window-management

Steuert, ob das aktuelle Dokument mit der Window Management API Fenster auf mehreren Bildschirmen verwalten darf.

xr-spatial-tracking

Steuert, ob das aktuelle Dokument mit der WebXR Device API mit einer WebXR-Sitzung interagieren darf.

Beispiele

Grundlegende Verwendung

Permissions-Policy-Header

Um allen Origins Zugriff auf Geolocation zu gewähren, verwenden Sie Folgendes:

Permissions-Policy: geolocation=*

Um den Zugriff nur für eine Auswahl von Origins zu erlauben, verwenden Sie Folgendes:

Permissions-Policy: geolocation=(self "https://a.example.com" "https://b.example.com")

Sie können mehrere Funktionen gleichzeitig steuern, indem Sie einen Header mit einer durch Kommas getrennten Liste von Richtlinien senden oder für jede Richtlinie einen separaten Header verwenden.

Die folgenden Varianten sind beispielsweise 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

Die Allowlist im Permissions-Policy-Header legt für eine Funktion die Obermenge der Origins fest, denen potenziell Zugriff auf diese Funktion gewährt werden kann. Das allow-Attribut eines <iframe>-Elements gewährt den darin genannten Origins Zugriff auf eine Funktion, sofern sie zu dieser Obermenge gehören. Aufgrund dieses Vererbungsverhaltens empfiehlt es sich, im HTTP-Header den größtmöglichen akzeptablen Zugriff auf eine Funktion festzulegen und dann in jedem <iframe>-Element die benötigte Teilmenge anzugeben.

Um allen Origins Zugriff auf Geolocation zu gewähren, verwenden Sie Folgendes:

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

Um eine Richtlinie auf die aktuelle und weitere Origins anzuwenden, verwenden Sie Folgendes:

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

Wichtig: Wenn ein <iframe>-Element zu einer anderen Origin navigiert, wird die Richtlinie standardmäßig nicht auf diese Origin angewendet. Wenn Sie die Origin, zu der das <iframe>-Element navigiert, im allow-Attribut aufführen, wird die auf das ursprüngliche <iframe>-Element angewendete Permissions Policy auch auf die neue Origin angewendet.

Sie können mehrere Funktionen gleichzeitig steuern, indem Sie im allow-Attribut eine durch Semikolons getrennte Liste von Richtliniendirektiven angeben.

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

Der Wert src verdient besondere Erwähnung. Wie oben beschrieben, ist die zugehörige Funktion bei Verwendung dieses Allowlist-Werts in einem <iframe>-Element erlaubt, sofern das darin geladene Dokument dieselbe Origin hat wie die URL in seinem Attribut src. Dieser Wert ist der Standardwert der allowlist für Funktionen, die im allow-Attribut aufgeführt sind. Daher sind die folgenden Varianten gleichwertig:

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

Zugriff auf leistungsfähige Funktionen verweigern

SecureCorp Inc. möchte in seiner Anwendung die APIs für Mikrofonzugriff (beispielsweise MediaDevices.getUserMedia()) und Geolocation deaktivieren. Dazu kann das Unternehmen den folgenden Antwort-Header verwenden:

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

Durch die Angabe von () als Origin-Liste werden die genannten Funktionen für alle Browsing-Kontexte (einschließlich aller <iframe>-Elemente) unabhängig von deren Origin deaktiviert.

HTTP-Header und <iframe>-Richtlinien kombinieren

Angenommen, wir möchten die Verwendung von Geolocation für unsere eigene Origin und für eingebettete Inhalte unseres vertrauenswürdigen Werbenetzwerks ermöglichen. Die seitenweite Permissions Policy könnten wir so festlegen:

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

In unseren Werbe-<iframe>-Elementen könnten wir den Zugriff für die Origin https://trusted-ad-network.com folgendermaßen festlegen:

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

Wenn stattdessen eine andere Origin in das <iframe>-Element geladen wird, hat sie keinen Zugriff auf Geolocation:

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

Verstöße melden

Dieses Beispiel zeigt, wie Sie die Meldung von Verstößen gegen Permissions-Policy an einen Server-Endpunkt konfigurieren.

Die folgenden Antwort-Header blockieren Geolocation und legen „geo_endpoint“ als Namen des Reporting-Endpunkts für diese Funktion fest. Mit dem HTTP-Antwort-Header Reporting-Endpoints wird die URL für diesen Endpunktnamen definiert.

Reporting-Endpoints: geo_endpoint="https://example.com/reports"
Permissions-Policy: geolocation=();report-to=geo_endpoint

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

Ein Verstoß tritt auf, wenn eine Seite versucht, die blockierte Funktion zu verwenden, beispielsweise so:

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

Die an den Endpunkt gesendeten Berichtsdaten könnten folgendermaßen 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
• Permissions-Policy-Report-Only
• Document.featurePolicy und FeaturePolicy
• Content-Security-Policy
• Referrer-Policy
• Reporting-Endpoints
• PermissionsPolicyViolationReport
• ReportingObserver
• Reporting API