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

Der Header kann verwendet werden, um die Erlaubnislisten (Allowlists) für eine oder mehrere Direktiven festzulegen, und optional einen per Direktive report-to Parameter anzugeben, der den Serverendpunkt angibt, an den Richtlinienverletzungsberichte gesendet werden sollen. Die Einträge für jede Direktive sind durch Kommas getrennt.

<directive>

Die Permissions-Policy-Direktive, auf die die allowlist angewendet werden soll. Siehe Direktiven unten für eine Liste der erlaubten Direktivnamen.

<allowlist>

Eine Erlaubnisliste (Allowlist) ist eine Liste von Ursprüngen, die einen oder mehrere der folgenden Werte in Klammern enthält, getrennt durch Leerzeichen:

* (Wildcard)

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

() (leere Allowlist)

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

self

Die Funktion wird in diesem Dokument und in allen verschachtelten Browsing-Kontexten (<iframe>s) nur im selben Ursprung erlaubt. Die Funktion ist nicht in verschachtelten Browsing-Kontexten mit Dokumenten aus fremden Ursprüngen erlaubt. self kann als Abkürzung 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 darin geladenen Dokument aus demselben Ursprung wie die URL in seinem src-Attribut stammt. Dieser Wert wird nur im <iframe> allow-Attribut verwendet und ist der Standard allowlist Wert in <iframe>s.

"<origin>"

Die Funktion ist für bestimmte 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 können.

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

report-to=<endpoint> Optional

Der report-to Parameter kann verwendet werden, um den Namen eines Berichterstattungsendpunkts anzugeben, an den Berichte gesendet werden, wenn es zu einer Richtlinienverletzung für die zugehörige Direktive kommt. Der Endpunktname und die zugehörige URL müssen in einem separaten Reporting-Endpoints HTTP-Antwort-Header angegeben werden.

Wenn er weggelassen wird, werden Berichte an den default-Berichterstattungsendpunkt gesendet, wenn einer definiert wurde. Siehe Reporting API für weitere Informationen.

Wo unterstützt, können Sie Platzhalter in Permissions-Policy Ursprüngen einfügen. Das bedeutet, dass anstelle mehrerer verschiedener Subdomains in einer Allowlist explizit angeben zu müssen, können Sie sie alle in einem einzigen Ursprung mit einem Platzhalter angeben.

Anstelle von:

("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

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

ambient-light-sensor

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

aria-notify

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

attribution-reporting

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

autoplay

Steuert, ob das aktuelle Dokument Medien, die über die HTMLMediaElement Schnittstelle angefordert wurden, automatisch abspielen darf. Wenn diese Richtlinie deaktiviert ist und keine Benutzeraktionen ausgeführt wurden, wird das Promise, das von HTMLMediaElement.play() zurückgegeben wird, mit einem NotAllowedError DOMException zurückgewiesen. Das Autoplay-Attribut bei <audio> und <video> Elementen wird ignoriert.

bluetooth

Steuert, ob die Verwendung 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 das zurückgegebene Promise mit einem SecurityError DOMException ab.

browsing-topics

Steuert den Zugriff auf die Topics API. Wenn eine Richtlinie die Verwendung der Topics API ausdrücklich verbietet, schlägt jeder Versuch, die Document.browsingTopics() Methode aufzurufen oder eine Anfrage mit einem Sec-Browsing-Topics Header zu senden, mit einem NotAllowedError DOMException fehl.

camera

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

captured-surface-control

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

ch-ua-high-entropy-values

Steuert, ob das Dokument die Methode NavigatorUAData.getHighEntropyValues() verwenden darf, um hochauflösende Benutzeragenten-Daten abzurufen. Wenn die Berechtigung nicht erteilt ist, gibt die Methode nur die brands, mobile und platform Niedrigauflösungsdaten 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 der [fetchLater()]-Quote (/de/docs/Web/API/Fetch_API/Using_Deferred_Fetch#quotas) des obersten Ursprungs.

deferred-fetch-minimal

Steuert die Zuweisung der gemeinsamen cross-origin-Unterrechtsfetisch-Quote fetchLater().

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 Versprechen mit einem NotAllowedError DOMException abgelehnt, wenn die Berechtigung nicht erteilt wurde, um den Bildschirminhalt zu erfassen.

encrypted-media

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

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

gamepad

Steuert, ob das aktuelle Dokument die Gamepad API verwenden darf. Wenn diese Richtlinie deaktiviert ist, führen Aufrufe von Navigator.getGamepads() zu einem SecurityError DOMException, und die gamepadconnected und gamepaddisconnected Ereignisse 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

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

hid

Steuert, ob das aktuelle Dokument die WebHID API verwenden darf, um sich mit unüblichen oder exotischen Human Interface Devices, wie alternativen Tastaturen oder Gamepads, zu verbinden.

identity-credentials-get

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

idle-detection

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

language-detector

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

language-model

Steuert den Zugriff auf die Prompt API.

local-fonts

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

local-network

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

local-network-access

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

loopback-network

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

magnetometer

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

microphone

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

midi

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

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

otp-credentials

Steuert, 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, d.h. über navigator.credentials.get({otp: ..., ...}).

payment

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

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

private-state-token-issuance

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

private-state-token-redemption

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

publickey-credentials-create

Steuert, ob das aktuelle Dokument die Web Authentication API verwenden darf, um neue asymmetrische Schlüsselberechtigungen 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 Public-Key-Anmeldedaten abzurufen, d.h. über navigator.credentials.get({publicKey: ..., ...}).

screen-wake-lock

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

serial

Steuert, ob das aktuelle Dokument die Web Serial API verwenden darf, um mit seriellen Geräten zu kommunizieren, die direkt über einen seriellen Port oder über USB- oder Bluetooth-Geräte emulieren einen seriellen Port verbunden sind.

speaker-selection

Steuert, ob das aktuelle Dokument die Audio Output Devices API verwenden darf, um Lautsprecher aufzulisten und auszuwählen.

storage-access

Steuert, ob ein in einem Drittanbieter-Kontext geladenes Dokument (d.h. eingebettet in einem <iframe>) die Storage Access API verwenden darf, um den Zugriff auf nicht partitionierte Cookies anzufordern.

translator

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

summarizer

Steuert den Zugriff auf die Summarizer API.

usb

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

web-share

Steuert, ob das aktuelle Dokument die Methode Navigator.share() der Web Share API verwenden darf, um Texte, Links, Bilder und andere Inhalte an beliebige Zielorte zu teilen, die der Benutzer auswählt, z.B. mobile Apps.

window-management

Steuert, ob das aktuelle Dokument die Window Management API verwenden darf, um Fenster auf mehreren Bildschirmen zu verwalten.

xr-spatial-tracking

Steuert, ob das aktuelle Dokument die WebXR Device API verwenden darf, um mit einer WebXR-Session zu interagieren.

Beispiele

Grundlegende Nutzung

Permissions-Policy-Header

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

Permissions-Policy: geolocation=*

Oder um den Zugriff auf eine Teilmenge von Ursprüngen zu ermöglichen, 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 komma-separierten Liste von Richtlinien gesendet wird, oder indem ein separater Header für jede Richtlinie 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 sein erlaubter Ursprung in der Allowlist der übergeordneten Seite stehen. Aufgrund dieses Vererbungsverhaltens ist es eine gute Idee, die weitestgehende Unterstützung für eine Funktion im HTTP-Header anzugeben und dann die benötigte Unterstützung in jedem <iframe> zu spezifizieren.

Um allen Ursprüngen Zugriff auf die Geolokalisierung zu ermöglichen, 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, wenn ein <iframe> zu einem anderen Ursprung navigiert, die Richtlinie nicht auf den Ursprung angewendet, zu dem das <iframe> navigiert. Indem der Ursprung, zu dem das <iframe> navigiert, im allow Attribut aufgeführt wird, 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 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>

Der src-Wert verdient eine besondere Erwähnung. Wir erwähnten oben, dass die Verwendung dieses Allowlist-Werts bedeutet, dass die zugehörige Funktion in diesem <iframe> erlaubt wird, solange das darin geladene Dokument aus demselben Ursprung wie die URL in seinem src-Attribut stammt. Dieser Wert ist der Standard allowlist-Wert für im allow aufgelistete Funktionen, sodass die folgenden gleichwertig sind:

<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 Mikrofon- (zum Beispiel MediaDevices.getUserMedia()) und Geolocation-APIs in seiner Anwendung deaktivieren. Dazu kann es den folgenden Antwort-Header verwenden:

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

Indem () für die Ursprungs-Liste angegeben wird, 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

Beispielsweise möchten wir vielleicht die Nutzung der Geolokalisierung auf unserem eigenen Ursprung und in eingebetteten Inhalten von unserem vertrauenswürdigen Anzeigen-Netzwerk ermöglichen. 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 https://trusted-ad-network.com Ursprung so einrichten:

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

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

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

Verstöße melden

Dieses Beispiel zeigt, wie die Berichterstattung von Permissions-Policy Verstößen zu einem Serverendpunkt konfiguriert wird.

Die unten stehenden Antwort-Header blockieren die Geolokalisierung und definieren den Berichterstattungsendpunktnamen für die Funktion als "geo_endpoint". Der Reporting-Endpoints HTTP-Antwort-Header wird verwendet, um die URL dieses Endpunktnamens zu definieren.

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, zum Beispiel:

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

Die Berichtsnutzlast, die an den Endpunkt gesendet wird, könnte 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