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 Zulassungslisten für eine oder mehrere Direktiven festzulegen und optional einen report-to-Parameter pro Direktive anzugeben, der den Server-Endpunkt angibt, an den Berichte über Richtlinienverstöße gesendet werden sollen. Die Einträge für jede Direktive sind durch Kommata 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 Zulassungsliste ist eine Liste von Ursprüngen, die einen oder mehrere der folgenden Werte enthält, eingeschlossen in Klammern und durch Leerzeichen getrennt:

* (Wildcard)

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

() (leere Zulassungsliste)

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) nur im selben Ursprung erlaubt. Die Funktion ist in Dokumenten mit Ursprüngen in geschachtelten 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 demselben Ursprung wie die URL in seinem src-Attribut stammt. Dieser Wert wird nur im <iframe>-allow-Attribut verwendet und ist der Standardwert für die allowlist 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 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 Standard-Zulassungsliste, die immer eines von *, self oder none für den Permissions-Policy-HTTP-Header ist und das Standardverhalten bestimmt, wenn sie nicht explizit in einer Richtlinie aufgeführt werden. Diese sind auf den einzelnen Richtlinienverweisseiten 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 einen Richtlinienverstoß für die zugehörige Direktive gibt. Der Endpunktname und die zugehörige URL müssen in einem separaten Reporting-Endpoints HTTP-Antwort-Header angegeben werden.

Wird er weggelassen, werden Berichte an den default-Berichterstattungsendpunkt gesendet, wenn einer definiert wurde. Weitere Informationen finden Sie in der Reporting API.

Wo unterstützt, können Sie Wildcards in den Ursprüngen der Permissions Policy einschließen. Das bedeutet, dass Sie anstelle der expliziten Angabe mehrerer verschiedener Subdomains in einer Zulassungsliste, diese alle in einem einzelnen Ursprung mit einer Wildcard angeben können.

Also statt:

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

Können Sie dies angeben:

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

Direktiven

accelerometer Experimentell

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

ambient-light-sensor Experimentell

Steuert, ob das aktuelle Dokument Informationen über die Lichtmenge in der Umgebung des Geräts über die AmbientLightSensor-Schnittstelle 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 über die HTMLMediaElement-Schnittstelle automatisch abspielen darf. Wenn diese Richtlinie deaktiviert ist und keine Benutzeraktionen durchgeführt wurden, 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 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 Veraltet Nicht standardisiert

Steuert den Zugriff auf die Topics API. Wenn eine Richtlinie die Nutzung der Topics API ausdrücklich nicht erlaubt, 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 Experimentell

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

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

ch-ua-high-entropy-values Experimentell

Steuert, ob das Dokument die NavigatorUAData.getHighEntropyValues()-Methode verwenden darf, um hochentropische User-Agent-Daten abzurufen. Wenn die Erlaubnis nicht erteilt wird, gibt die Methode nur die niederentropischen Daten brands, mobile und platform zurück.

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 freigegebenen, ursprungübergreifenden Subframe-Quotas für fetchLater().

display-capture Experimentell

Steuert, ob das aktuelle Dokument die getDisplayMedia()-Methode zur Erfassung von Bildschirminhalten verwenden darf. Wenn diese Richtlinie deaktiviert ist, lehnt das von getDisplayMedia() zurückgegebene Promise mit einem NotAllowedError DOMException ab, wenn keine Erlaubnis zur Erfassung der Bildschirm-Anzeige erhalten wird.

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, 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, führen Aufrufe von Navigator.getGamepads() zu einem SecurityError DOMException, und die gamepadconnected- und gamepaddisconnected-Events werden nicht ausgelöst.

geolocation Experimentell

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ückruffunktionen dieser Funktionen mit einem GeolocationPositionError-Code von PERMISSION_DENIED aufgerufen werden.

gyroscope Experimentell

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

hid Experimentell

Steuert, ob das aktuelle Dokument die Verwendung der WebHID API zum Verbinden mit ungewöhnlichen oder exotischen Mensch-Maschine-Schnittstellengeräten wie alternativen Tastaturen oder Gamepads erlaubt ist.

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, um beispielsweise den Status "verfügbar"/"abwesend" in Chat-Anwendungen anzugeben.

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 auf dem Benutzer lokal installierte Schriftarten über die Window.queryLocalFonts()-Methode sammeln darf (siehe auch die Local Font Access API).

magnetometer Experimentell

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

microphone Experimentell

Steuert, ob das aktuelle Dokument Audioeingabegeräte verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das von MediaDevices.getUserMedia() zurückgegebene Promise 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 von Navigator.requestMIDIAccess() zurückgegebene Promise mit einem SecurityError DOMException zurückgewiesen.

on-device-speech-recognition Experimentell

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

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, löst der PaymentRequest()-Konstruktor eine SecurityError DOMException aus.

picture-in-picture Experimentell

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

private-state-token-issuance Experimentell

Steuert die Verwendung von Private State Token-token-request-Operationen.

private-state-token-redemption Experimentell

Steuert die Verwendung 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 asymmetrische Schlüsselanmeldeinformationen zu erstellen, d.h. über navigator.credentials.create({publicKey: ..., ...}).

publickey-credentials-get Experimentell

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 Experimentell

Steuert, ob das aktuelle Dokument die Screen Wake Lock API verwenden darf, um anzuzeigen, 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 mit seriellen Geräten zu kommunizieren, die entweder direkt über einen seriellen Port angeschlossen sind oder über USB- oder Bluetooth-Geräte, die einen seriellen Port emulieren.

speaker-selection Experimentell

Steuert, ob das aktuelle Dokument die Audio-Ausgabegeräte-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 einem <iframe>) die Storage Access API verwenden darf, um Zugriff auf unpartitionierte 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()-Methode der Web Share API verwenden darf, um Text, Links, Bilder und andere Inhalte zu beliebigen Zielen 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 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 Nutzung

Permissions-Policy-Header

Um allen Ursprüngen Zugriff auf Geolocation zu gewähren, 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 kommagetrennten Liste von Richtlinien gesendet oder 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 Zulassungsliste 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 das Untermenge an Unterstützung, die Sie in jedem <iframe> benötigen, anzugeben.

Um allen Ursprüngen Zugriff auf Geolocation zu gewähren, würden Sie dies tun:

<iframe src="proxy.php?url=https%3A%2F%2Fexample.com" allow="geolocation *"></iframe>

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

<iframe
  src="proxy.php?url=https%3A%2F%2Fexample.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. Durch die Auflistung des Ursprungs, zu dem das <iframe> im allow-Attribut navigiert, 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 angegeben wird.

<iframe
  src="proxy.php?url=https%3A%2F%2Fexample.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 schenken. Wir haben oben erwähnt, dass die Verwendung dieses Zulassungslistenwerts bedeutet, dass die zugehörige Funktion in diesem <iframe> erlaubt ist, solange das darin geladene Dokument aus demselben Ursprung wie die URL in seinem src-Attribut stammt. Dieser Wert ist der Standardallowlist-Wert für Funktionen, die in allow aufgeführt sind, sodass die folgenden gleichwertig sind:

<iframe src="proxy.php?url=https%3A%2F%2Fexample.com" allow="geolocation 'src'"></iframe>
<iframe src="proxy.php?url=https%3A%2F%2Fexample.com" allow="geolocation"></iframe>

Zugriff auf leistungsstarke Funktionen verweigern

SecureCorp Inc. möchte die Microphone-Funktion (zum Beispiel MediaDevices.getUserMedia()) und die Geolocation-APIs in seiner Anwendung deaktivieren. Es kann dies mit dem folgenden Antwort-Header tun:

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

Durch Angabe von () für die Ursprungs-Liste 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

Zum Beispiel, nehmen wir an, wir möchten die Nutzung von Geolocation auf unserem eigenen Ursprung und in eingebetteten Inhalten unseres vertrauenswürdigen Werbenetzwerkes ermöglichen. Wir könnten die seitenweite Permissions Policy folgendermaßen 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="proxy.php?url=https%3A%2F%2Ftrusted-ad-network.com" allow="geolocation"></iframe>

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

<iframe src="proxy.php?url=https%3A%2F%2Frogue-origin-example.com" allow="geolocation"></iframe>

Berichten von Verstößen

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

Die unten stehenden Antwort-Header blockieren die Geolocation und definieren den Namen des Berichterstattungs-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 gesperrte Funktion zu verwenden, zum Beispiel:

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

Die an den Endpunkt gesendete Reporte-Nutzlast 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
• Permissions-Policy-Report-Only
• Document.featurePolicy und FeaturePolicy
• Content-Security-Policy
• Referrer-Policy
• Reporting-Endpoints
• PermissionsPolicyViolationReport
• ReportingObserver
• Reporting API