Permissions-Policy header

Eingeschränkt verfügbar

Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Der HTTP Permissions-Policy Antwort-Header bietet einen Mechanismus, um die Nutzung von Browser-Funktionen in einem Dokument oder innerhalb von <iframe>-Elementen im Dokument zu erlauben oder zu verweigern.

Verletzungen einer Richtlinie können mit der Reporting API gemeldet werden. Berichte können an einen Server gesendet werden, der mit einem Namen in einem pro-Richtlinie angegebenen report-to-Parameter angegeben ist, oder andernfalls an den Serverendpunkt namens "default" (die Zuordnung zwischen Serverendpunktnamen und URLs wird mit dem Reporting-Endpoints HTTP-Antwort-Header festgelegt). Berichte können auch auf der Seite beobachtet werden, für die die Richtlinie durchgesetzt wird, unter Verwendung eines ReportingObserver. Das Format des Berichts und zusätzliche Details werden in PermissionsPolicyViolationReport bereitgestellt.

Weitere Informationen finden Sie im Hauptartikel zur Permissions-Policy.

Header-Typ	Antwort-Header

Syntax

http

# 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 Allowlists für eine oder mehrere Direktiven festzulegen und optional einen report-to-Parameter pro Direktive anzugeben, der den Serverendpunkt angibt, an den Berichte über Richtlinienverletzungen 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 unten Direktiven für eine Liste der erlaubten Direktivnamen.

<allowlist>

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

* (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 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) nur im gleichen Ursprung erlaubt. Die Funktion ist in eingebetteten Browsing-Kontexten über Ursprungsgrenzen hinweg nicht erlaubt. self kann als Kurzform für https://your-site.example.com angesehen werden. Das Äquivalent für <iframe>-allow-Attribute ist self.
src: Die Funktion wird in diesem <iframe> erlaubt, solange das darin geladene Dokument vom gleichen Ursprung wie die URL in seinem src-Attribut stammt. Dieser Wert wird nur im <iframe>-allow-Attribut verwendet und ist der Standardallowlist-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 sein. Beachten Sie, dass Ursprünge in <iframe>-allow-Attributen nicht in Anführungszeichen geschrieben werden.

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

Hinweis: Direktiven haben eine Standard-Allowlist, die immer eines von *, self oder none für den Permissions-Policy HTTP-Header ist, und regelt das Standardverhalten, wenn sie nicht explizit in einer Richtlinie aufgeführt sind. Diese sind auf den einzelnen Direktivreferenzseiten 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 Berichts-Endpunkts anzugeben, an den Berichte gesendet werden, wenn eine Richtlinienverletzung für die zugehörige Direktive vorliegt. 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-Berichts-Endpunkt gesendet, falls einer definiert wurde. Siehe Reporting API für weitere Informationen.

Wo unterstützt, können Sie Platzhalter in Permissions Policy Ursprüngen enthalten. Dies bedeutet, dass Sie, anstatt explizit mehrere verschiedene Subdomänen in einer Allowlist anzugeben, alle in einem einzigen Ursprung mit einem Platzhalter angeben können.

Anstatt also:

http

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

könnten Sie angeben:

http

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

Hinweis: "https://*.example.com" entspricht nicht "https://example.com".

Direktiven

accelerometer: Steuert, ob dem aktuellen Dokument erlaubt ist, Informationen über die Beschleunigung des Geräts über die Accelerometer-Schnittstelle zu sammeln.
ambient-light-sensor: Steuert, ob dem aktuellen Dokument erlaubt ist, Informationen über die Lichtmenge in der Umgebung des Geräts über die AmbientLightSensor-Schnittstelle zu sammeln.
aria-notify: Steuert, ob dem aktuellen Dokument erlaubt ist, die ariaNotify()-Methode zu verwenden, um Screenreader-Ankündigungen auszuführen.
attribution-reporting: Steuert, ob dem aktuellen Dokument erlaubt ist, die Attribution Reporting API zu verwenden.
autoplay: Steuert, ob dem aktuellen Dokument erlaubt ist, Medien automatisch abzuspielen, die über die HTMLMediaElement-Schnittstelle angefordert werden. Wenn diese Richtlinie deaktiviert ist und keine Nutzerinteraktionen erfolgt sind, wird das Promise, das von HTMLMediaElement.play() zurückgegeben wird, mit einem NotAllowedError DOMException abgelehnt. Das autoplay-Attribut auf <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. Wo eine Richtlinie die Verwendung der Topics API explizit 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 dem aktuellen Dokument erlaubt ist, Video-Eingabegeräte zu verwenden. Das von getUserMedia() zurückgegebene Promise wird mit einem NotAllowedError DOMException abgelehnt, wenn die Berechtigung nicht erlaubt 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 erlaubt ist.
ch-ua-high-entropy-values: Steuert, ob das Dokument die Methode NavigatorUAData.getHighEntropyValues() verwenden darf, um hochentropische User-Agent-Daten abzurufen. Wenn die Berechtigung nicht erlaubt ist, gibt die Methode nur die niederige Entropiedaten 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 isolated behandelt werden kann.
deferred-fetch: Steuert die Zuweisung des fetchLater()-Kontingents des höchstleveligen Ursprungs.
deferred-fetch-minimal: Steuert die Zuweisung des gemeinsamen originübergreifenden Unterrahmen- fetchLater()-Kontingents.
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 bei fehlender Erlaubnis zur Erfassung der Display-Inhalte mit einem NotAllowedError DOMException abgelehnt.
encrypted-media: Steuert, ob dem aktuellen Dokument die Verwendung der Encrypted Media Extensions API (EME) erlaubt ist. Wenn diese Richtlinie deaktiviert ist, wird das von Navigator.requestMediaKeySystemAccess() zurückgegebene Promise mit einem SecurityError DOMException abgelehnt.
fullscreen: Steuert, ob dem aktuellen Dokument die Verwendung von Element.requestFullscreen() erlaubt ist. Wenn diese Richtlinie deaktiviert ist, lehnt das zurückgegebene Promise mit einem TypeError ab.
gamepad: Steuert, ob dem aktuellen Dokument die Verwendung der Gamepad API erlaubt ist. Wenn diese Richtlinie deaktiviert ist, werfen Aufrufe an Navigator.getGamepads() einen SecurityError DOMException, und die gamepadconnected und gamepaddisconnected Ereignisse werden nicht ausgelöst.
geolocation: Steuert, ob dem aktuellen Dokument die Verwendung der Geolocation-Schnittstelle erlaubt ist. Wenn diese Richtlinie deaktiviert ist, bewirken Aufrufe von getCurrentPosition() und watchPosition(), dass die Rückrufe dieser Funktionen mit einem GeolocationPositionError Code von PERMISSION_DENIED aufgerufen werden.
gyroscope: Steuert, ob dem aktuellen Dokument erlaubt ist, Informationen über die Ausrichtung des Geräts über die Gyroscope-Schnittstelle zu sammeln.
hid: Steuert, ob dem aktuellen Dokument die Verwendung der WebHID API erlaubt ist, um eine Verbindung zu ungewöhnlichen oder exotischen Mensch-Maschine-Schnittgeräte wie alternativen Tastaturen oder Gamepads herzustellen.
identity-credentials-get: Steuert, ob dem aktuellen Dokument die Verwendung der Federated Credential Management API (FedCM) erlaubt ist.
idle-detection: Steuert, ob dem aktuellen Dokument die Verwendung der Idle Detection API erlaubt ist, um zu erkennen, wann Nutzer mit ihren Geräten interagieren, zum Beispiel 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.
local-fonts: Steuert, ob dem aktuellen Dokument die Erfassung von Daten zu den lokal installierten Schriften des Nutzers über die Methode Window.queryLocalFonts() erlaubt ist (siehe auch die Local Font Access API).
magnetometer: Steuert, ob dem aktuellen Dokument erlaubt ist, Informationen über die Ausrichtung des Geräts über die Magnetometer-Schnittstelle zu sammeln.
microphone: Steuert, ob dem aktuellen Dokument die Verwendung von Audioeingabegeräten erlaubt ist. Wenn diese Richtlinie deaktiviert ist, wird das von MediaDevices.getUserMedia() zurückgegebene Promise mit einem NotAllowedError DOMException abgelehnt.
midi: Steuert, ob dem aktuellen Dokument die Verwendung der Web MIDI API erlaubt ist. Wenn diese Richtlinie deaktiviert ist, wird das von Navigator.requestMIDIAccess() zurückgegebene Promise mit einem SecurityError DOMException abgelehnt.
on-device-speech-recognition: Steuert den Zugriff auf die on-device speech recognition-Funktionalität der Web Speech API.
otp-credentials: Steuert, ob dem aktuellen Dokument die Verwendung der WebOTP API erlaubt ist, um ein Einmalpasswort (OTP) aus einer speziell formatierten SMS-Nachricht anzufordern, die vom Server der App gesendet wird, z.B. über navigator.credentials.get({otp: ..., ...}).
payment: Steuert, ob dem aktuellen Dokument die Verwendung der Payment Request API erlaubt ist. Wenn diese Richtlinie aktiviert ist, wird der PaymentRequest()-Konstruktor einen SecurityError DOMException auslösen.
picture-in-picture: Steuert, ob dem aktuellen Dokument erlaubt ist, ein Video in einem Bild-im-Bild-Modus über die entsprechende API abzuspielen.
private-state-token-issuance: Steuert die Verwendung von private state token token-request-Operationen.
private-state-token-redemption: Steuert die Verwendung von private state token token-redemption- und send-redemption-record-Operationen.
publickey-credentials-create: Steuert, ob dem aktuellen Dokument die Verwendung der Web Authentication API erlaubt ist, um neue asymmetrische Schlüsselanmeldeinformationen zu erstellen, z.B. über navigator.credentials.create({publicKey: ..., ...}).
publickey-credentials-get: Steuert, ob dem aktuellen Dokument die Verwendung der Web Authentication API erlaubt ist, um bereits gespeicherte Public-Key-Anmeldeinformationen abzurufen, z.B. über navigator.credentials.get({publicKey: ..., ...}).
screen-wake-lock: Steuert, ob das aktuelle Dokument die Verwendung der Screen Wake Lock API erlauben darf, um anzuzeigen, dass das Gerät den Bildschirm nicht ausschalten oder dimmen soll.
serial: Steuert, ob dem aktuellen Dokument die Verwendung der Web Serial API erlaubt ist, um mit seriellen Geräten zu kommunizieren, entweder direkt über einen seriellen Anschluss oder über USB- oder Bluetooth-Geräte, die einen seriellen Anschluss emulieren.
speaker-selection: Steuert, ob das aktuelle Dokument die Verwendung der Audio Output Devices API erlauben darf, um Lautsprecher aufzulisten und auszuwählen.
storage-access: Steuert, ob ein in einem Drittkontext geladenes Dokument (d.h. eingebettet in ein <iframe>) die Storage Access API verwenden darf, um Zugriff auf unpartitionierte 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 dem aktuellen Dokument die Verwendung der WebUSB API erlaubt ist.
web-share: Steuert, ob dem aktuellen Dokument erlaubt ist, die Navigator.share() der Web Share API zu verwenden, um Text, Links, Bilder und andere Inhalte an beliebige, vom Benutzer ausgewählte Ziele zu teilen, z.B. mobile Apps.
window-management: Steuert, ob das aktuelle Dokument die Verwendung der Window Management API erlauben darf, um Fenster auf mehreren Anzeigen zu verwalten.
xr-spatial-tracking: Steuert, ob das aktuelle Dokument die Verwendung der WebXR Device API erlauben darf, um mit einer WebXR-Sitzung zu interagieren.

Beispiele

Grundlegende Nutzung

Permissions-Policy-Header

Um allen Ursprüngen den Zugriff auf Geolocation zu erlauben, würden Sie folgendes tun:

http

Permissions-Policy: geolocation=*

Oder um den Zugriff auf eine Teilmenge von Ursprüngen zu erlauben, würden Sie dies tun:

http

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 Kommas getrennten Liste von Richtlinien gesendet wird, oder indem ein separater Header für jede Richtlinie gesendet wird.

Zum Beispiel sind die folgenden gleichwertig:

http

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 Allowlist der übergeordneten Seite enthalten sein. Aufgrund dieses Vererbungsvorgehens ist es eine gute Idee, die breiteste akzeptable Unterstützung für eine Funktion im HTTP-Header festzulegen und dann den gewünschten Unterstützungsbereich in jedem <iframe> zu spezifizieren.

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

html

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

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

html

<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, zu dem das <iframe> navigiert, wenn es zu einem anderen Ursprung navigiert. Durch die Auflistung des Ursprungs, zu dem das <iframe> navigiert, im allow-Attribut wird die ursprünglich auf das <iframe> angewendete Permissions-Policy auch 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.

html

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

Es ist erwähnenswert, den src-Wert besonders zu erwähnen. Wir haben oben erwähnt, dass die Verwendung dieses Allowlist-Wertes bedeutet, dass die zugehörige Funktion in diesem <iframe> erlaubt wird, solange das darin geladene Dokument vom gleichen Ursprung wie die URL in seinem src-Attribut stammt. Dieser Wert ist der Standardallowlist-Wert für Funktionen, die in allow aufgelistet sind, sodass die folgenden äquivalent sind:

html

<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 Microphone (z.B. MediaDevices.getUserMedia()) und Geolocation APIs in ihrer Anwendung deaktivieren. Sie können dies mit dem folgenden Antwort-Header tun:

http

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

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

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

Zum Beispiel, nehmen wir an, wir wollten die Nutzung von Geolocation auf unserem eigenen Ursprung und in eingebettetem Inhalt von unserem vertrauenswürdigen Ad-Netzwerk zulassen. Wir könnten die seitenweite Permissions-Policy wie folgt einrichten:

http

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

In unseren Anzeigen-<iframe>s könnten wir den Zugriff auf den Ursprung https://trusted-ad-network.com wie folgt festlegen:

html

<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 Geolocation:

html

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

Berichte über Verstöße

Dieses Beispiel zeigt, wie das Reporting von Permissions-Policy-Verstößen an einen Serverendpunkt konfiguriert werden kann.

Die untenstehenden Antwort-Header blockieren Geolocation und definieren den Bericht-Endpunktnamen für die Funktion als "geo_endpoint". Der Reporting-Endpoints HTTP-Antwort-Header wird verwendet, um die URL dieses Endpunktnamens zu definieren.

http

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

Hinweis: Um alle Berichtsverletzungen an den gleichen Endpunkt zu senden, könnten wir stattdessen den "default" Berichts-Endpunkt definieren:

http

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 Berichts-Nutzdaten, die an den Endpunkt gesendet werden, könnten wie folgt aussehen:

json

[
  {
    "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"
  }
]

Hinweis: Chromes serverseitige Serialisierung von Verstoßberichten verwendet policyId anstelle von featureId für den Funktionsnamen im body eines Serverberichts. Der von einem ReportingObserver zurückgegebene PermissionsPolicyViolationReport folgt der Spezifikation.

Spezifikationen

Spezifikation
Permissions Policy # permissions-policy-http-header-field

Browser-Kompatibilität

Siehe auch

Help improve MDN

Erfahren Sie, wie Sie beitragen können Diese Seite wurde automatisch aus dem Englischen übersetzt.

Übersetzung auf GitHub anzeigen • Fehler mit dieser Übersetzung melden