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 für eine oder mehrere Richtlinien festzulegen, optional mit einem report-to-Parameter pro Richtlinie, der den Server-Endpunkt angibt, zu dem Berichte über Richtlinienverstöße gesendet werden sollen. Die Einträge für jede Richtlinie werden durch Kommas getrennt.

<directive>

Die Permissions-Policy-Richtlinie, auf die die allowlist angewendet werden soll. Siehe Richtlinien unten für eine Liste der erlaubten Richtliniennamen.

<allowlist>

Eine Erlaubnisliste 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 eingebetteten Browsing-Kontexten (<iframe>s) ungeachtet ihres Ursprungs erlaubt.

() (leere Erlaubnisliste)

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

self

Die Funktion wird in diesem Dokument und in allen eingebetteten Browsing-Kontexten (<iframe>s) 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> allow-Attribute ist self.

src

Die Funktion wird in diesem <iframe> erlaubt, solange das darin geladene Dokument aus dem gleichen Ursprung wie die URL im src-Attribut stammt. Dieser Wert wird nur im <iframe> allow-Attribut verwendet und ist der default 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 dürfen.

Hinweis: Richtlinien haben eine Standard-Erlaubnisliste, die immer eine der *, 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 Richtlinienreferenzseiten spezifiziert. 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 Reporting-Endpunkts anzugeben, an den Berichte gesendet werden, wenn es einen Richtlinienverstoß für die zugehörige Richtlinie gibt. 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-Reporting-Endpunkt gesendet, wenn einer definiert wurde. Siehe Reporting API für mehr Informationen.

Wo unterstützt, können Sie Platzhalter in Ursprüngen der Permissions Policy einbeziehen. Dies bedeutet, dass Sie statt mehrere verschiedene Subdomains explizit in einer Erlaubnisliste anzugeben, sie alle in einem einzigen Ursprung mit einem Platzhalter angeben können.

Statt:

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

Richtlinien

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 Menge des Lichts 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 auszuführen.

attribution-reporting

Steuert den Zugriff auf die Attribution Reporting API.

autoplay

Steuert, ob das aktuelle Dokument Medien, die über die HTMLMediaElement Schnittstelle angefordert werden, automatisch abspielen darf. Wenn diese Richtlinie deaktiviert ist und keine Benutzeraktionen erfolgten, 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

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

Steuert den Zugriff auf die Topics API. Wo eine Richtlinie die Nutzung der Topics API ausdrücklich verbietet, werden alle Versuche, die Document.browsingTopics() Methode aufzurufen oder eine Anfrage mit einem Sec-Browsing-Topics Header zu senden, mit einem NotAllowedError DOMException fehlschlagen.

camera

Steuert, ob das aktuelle Dokument Videoinput-Geräte verwenden darf. Das Promise, das von getUserMedia() zurückgegeben wird, lehnt mit einem NotAllowedError DOMException ab, wenn die Erlaubnis nicht gestattet ist.

captured-surface-control

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 abgelehnt, wenn die Erlaubnis nicht erteilt ist.

ch-ua-high-entropy-values

Steuert, ob das Dokument die NavigatorUAData.getHighEntropyValues() Methode verwenden darf, um hoch-entzugsfreudige User-Agent-Daten abzurufen. Wenn die Erlaubnis nicht erteilt ist, wird die Methode nur die brands, mobile und platform niedrig-entzugsfreudige Daten zurückgeben.

compute-pressure

Steuert den Zugriff auf die Compute Pressure API.

cross-origin-isolated

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

deferred-fetch

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

deferred-fetch-minimal

Steuert die Zuweisung des geteilten Cross-Origin-Unterrahmen-fetchLater() Kontingents](/de/docs/Web/API/Fetch_API/Using_Deferred_Fetch#quotas).

display-capture

Steuert, ob das aktuelle Dokument die getDisplayMedia() Methode verwenden darf, um Bildschirm-Inhalte zu erfassen. Wenn diese Richtlinie deaktiviert ist, lehnt das von getDisplayMedia() zurückgegebene Promise mit einem NotAllowedError DOMException ab, wenn die Berechtigung zur Erfassung der Bildschirminhalte nicht erlangt wird.

encrypted-media

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, lehnt das zurückgegebene Promise mit einem TypeError ab.

gamepad

Steuert, ob das aktuelle Dokument die Gamepad API verwenden darf. Wenn diese Richtlinie deaktiviert ist, werfen Aufrufe von Navigator.getGamepads() einen 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, verursachen Aufrufe von getCurrentPosition() und watchPosition(), dass die Rückrufe 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 eine Verbindung mit ungewöhnlichen oder exotischen Mensch-Maschine-Schnittstellengerä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 die Idle Detection API verwenden darf, um zu erkennen, wann Benutzer mit ihren Geräten interagieren, beispielsweise um einen "verfügbar"/"abwesend"-Status in Chat-Anwendungen zu melden.

language-detector

Steuert den Zugriff auf die Sprachenerkennungsfunktionalität der Übersetzungs- und Sprachenerkennungs-APIs.

local-fonts

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

local-network

Steuert, ob das aktuelle Dokument Netzwerk-Anfragen an lokale Adressen senden darf.

local-network-access

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

loopback-network

Steuert, ob das aktuelle Dokument Netzwerk-Anfragen 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 Audio-Eingabegeräte verwenden darf. Wenn diese Richtlinie deaktiviert ist, lehnt das von MediaDevices.getUserMedia() zurückgegebene Promise mit einem NotAllowedError DOMException ab.

midi

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

on-device-speech-recognition

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

otp-credentials

Steuert, ob das aktuelle Dokument die WebOTP API nutzen 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 nutzen darf. Wenn diese Richtlinie aktiviert ist, wirft der PaymentRequest() Konstruktor einen SecurityError DOMException.

picture-in-picture

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

private-state-token-issuance

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

private-state-token-redemption

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

publickey-credentials-create

Steuert, ob das aktuelle Dokument die Web Authentication API nutzen 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 nutzen 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 nutzen darf, um anzuzeigen, dass das Gerät den Bildschirm nicht ausschalten oder verdunkeln soll.

serial

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

speaker-selection

Steuert, ob das aktuelle Dokument die Audio Output Devices API nutzen 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 nutzen darf, um Zugriff auf nicht partitionierte Cookies zu beantragen.

translator

Steuert den Zugriff auf die Übersetzungfunktionalität der Übersetzungs- und Sprachenerkennungs-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 Navigator.share() der Web Share API verwenden darf, um Texte, Links, Bilder und andere Inhalte an beliebige vom Benutzer ausgewählte Ziele, z.B. mobile Apps, zu teilen.

window-management

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

xr-spatial-tracking

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 den Zugriff auf Geolokation zu erlauben, würden Sie dies tun:

Permissions-Policy: geolocation=*

Oder um den Zugriff auf eine Teilmenge 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 gesteuert werden, indem der Header mit einer durch Kommata getrennten 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 sein erlaubter Ursprung auch in der Erlaubnisliste der übergeordneten Seite sein. Aufgrund dieses Vererbungsverhaltens ist es eine gute Idee, die breiteste akzeptable Unterstützung für eine Funktion im HTTP-Header anzugeben und dann die benötigte Teilmenge an Unterstützung in jedem <iframe> zu spezifizieren.

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

Dies ist wichtig: Standardmäßig gilt die Richtlinie nicht für den Ursprung, auf den das <iframe> navigiert, wenn ein <iframe> zu einem anderen Ursprung navigiert. Wenn der Ursprung, auf den das <iframe> navigiert, im allow-Attribut aufgelistet ist, 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 mit 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>

Es ist erwähnenswert, dem src-Wert besondere Aufmerksamkeit zu widmen. Wir haben oben erwähnt, dass die Verwendung dieses Erlaubnislistenwertes bedeutet, dass die zugehörige Funktion in diesem <iframe> erlaubt wird, solange das darin geladene Dokument aus dem gleichen Ursprung wie die URL im src-Attribut stammt. Dieser Wert ist der Standard allowlist-Wert für Funktionen, die in allow aufgelistet sind, daher sind die folgenden gleichwertig:

<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 seiner Anwendung deaktivieren. Dies kann mit dem folgenden Antwort-Header erreicht werden:

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

Durch die Angabe von () für die Ursprungsauflistung werden die angegebenen Funktionen für alle Browsing-Kontexte (einschließlich aller <iframe>s) deaktiviert, ungeachtet ihres Ursprungs.

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

Angenommen, wir möchten die Nutzung der Geolokalisierung auf unserem eigenen Ursprung und in eingebetteten Inhalten von unserem vertrauenswürdigen Ad-Netzwerk aktivieren. 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 wie folgt festlegen:

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

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

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

Verstöße melden

Dieses Beispiel zeigt, wie die Berichterstattung von Permissions-Policy-Verstößen an einen Server-Endpunkt konfiguriert wird.

Die untenstehenden Antwort-Header blockieren Geolokation und definieren den Namen des Reporting-Endpunkts 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 nutzen, zum Beispiel:

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

Die Berichtsladung, 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