Permissions-Policy header

Eingeschränkt verfügbar

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

Want more browser support for this feature? Tell us why.

Vollständige Kompatibilität anzeigen
Mehr erfahren

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-Response-Header bietet einen Mechanismus, um die Verwendung von Browserfunktionen in einem Dokument oder in darin enthaltenen <iframe>-Elementen zu erlauben oder zu verweigern.

Verstöße gegen eine Richtlinie können über die Reporting API gemeldet werden. Berichte können an einen Server gesendet werden, der in einem direktivspezifischen report-to-Parameter per Name angegeben ist, oder andernfalls an den Serverendpunkt mit dem Namen "default" (die Zuordnung zwischen Serverendpunktnamen und URLs wird über den HTTP-Response-Header Reporting-Endpoints festgelegt). Berichte können auch auf der Seite, für die die Richtlinie durchgesetzt wird, mithilfe eines ReportingObserver beobachtet werden. Das Format des Berichts und weitere Details werden in PermissionsPolicyViolationReport bereitgestellt.

Weitere Informationen finden Sie im Hauptartikel zu Permissions Policy.

Header-Typ	Response-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, sowie optional einen direktivspezifischen report-to-Parameter, der den Serverendpunkt angibt, an den Berichte über Richtlinienverstöße gesendet werden sollen. Die Einträge für jede Direktive werden durch Kommas getrennt.

<directive>

Die Permissions-Policy-Direktive, auf die die allowlist angewendet werden soll. Eine Liste der zulässigen Direktivnamen finden Sie weiter unten unter Direktiven.

<allowlist>

Eine Allowlist ist eine Liste von Origins, die einen oder mehrere der folgenden, in Klammern eingeschlossenen und durch Leerzeichen getrennten Werte enthält:

* (Wildcard): Die Funktion wird in diesem Dokument und in allen verschachtelten Browsing-Kontexten (<iframe>s) unabhängig von ihrem Origin erlaubt.
() (leere Allowlist): Die Funktion wird in Browsing-Kontexten der obersten Ebene und verschachtelten Browsing-Kontexten deaktiviert. Das Äquivalent für <iframe>-allow-Attribute ist 'none'.
self: Die Funktion wird in diesem Dokument und nur in allen verschachtelten Browsing-Kontexten (<iframe>s) mit demselben Origin erlaubt. Die Funktion ist in Cross-Origin-Dokumenten in verschachtelten Browsing-Kontexten 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, sofern das darin geladene Dokument vom selben Origin wie die URL in seinem src-Attribut stammt. Dieser Wert wird nur im <iframe>-allow-Attribut verwendet und ist der Standardwert für allowlist in <iframe>s.
"<origin>": Die Funktion ist für bestimmte Origins erlaubt (zum Beispiel "https://a.example.com"). Origins sollten durch Leerzeichen getrennt werden. Beachten Sie, dass Origins in <iframe>-allow-Attributen nicht in Anführungszeichen stehen.

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

Hinweis: Direktiven haben eine Standard-Allowlist, die für den HTTP-Header Permissions-Policy immer eine von *, self oder none ist und das Standardverhalten bestimmt, wenn sie nicht ausdrücklich in einer Richtlinie aufgeführt sind. Diese werden auf den jeweiligen Referenzseiten für Direktiven angegeben. Für <iframe>-allow-Attribute ist das Standardverhalten immer src.

report-to=<endpoint> Optional

Der Parameter report-to kann verwendet werden, um den Namen eines Reporting-Endpunkts anzugeben, an den Berichte gesendet werden, wenn ein Richtlinienverstoß für die zugehörige Direktive vorliegt. Der Endpunktname und seine zugehörige URL müssen in einem separaten HTTP-Response-Header Reporting-Endpoints angegeben werden.

Wenn er weggelassen wird, werden Berichte an den default-Reporting-Endpunkt gesendet, sofern einer definiert wurde. Weitere Informationen finden Sie unter Reporting API.

Wo unterstützt, können Sie Wildcards in Permissions-Policy-Origins einschließen. Das bedeutet, dass Sie nicht mehrere verschiedene Subdomains explizit in einer Allowlist angeben müssen, sondern sie alle in einem einzigen Origin mit einer Wildcard angeben können.

Also statt:

http

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

können Sie Folgendes angeben:

http

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

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

Direktiven

accelerometer: Steuert, ob das aktuelle Dokument über die Accelerometer-Schnittstelle Informationen über die Beschleunigung des Geräts erfassen darf.
ambient-light-sensor: Steuert, ob das aktuelle Dokument über die AmbientLightSensor-Schnittstelle Informationen über die Lichtmenge in der Umgebung des Geräts erfassen darf.
aria-notify: Steuert, ob das aktuelle Dokument die Methode ariaNotify() verwenden darf, um Ankündigungen für Screenreader auszulösen.
attribution-reporting: Steuert, ob das aktuelle Dokument die Attribution Reporting API verwenden darf.
autoplay: Steuert, ob das aktuelle Dokument Medien automatisch wiedergeben darf, die über die HTMLMediaElement-Schnittstelle angefordert werden. Wenn diese Richtlinie deaktiviert ist und keine Benutzerinteraktionen stattgefunden haben, wird das von HTMLMediaElement.play() zurückgegebene Promise mit einer NotAllowedError-DOMException abgelehnt. Das autoplay-Attribut der Elemente <audio> und <video> wird ignoriert.
bluetooth: Steuert, ob die Verwendung der Web Bluetooth API erlaubt ist. Wenn diese Richtlinie deaktiviert ist, geben die Methoden des von Navigator.bluetooth zurückgegebenen Bluetooth-Objekts entweder false zurück oder lehnen das zurückgegebene Promise mit einer SecurityError-DOMException ab.
browsing-topics: Steuert den Zugriff auf die Topics API. Wenn eine Richtlinie die Verwendung der Topics API ausdrücklich untersagt, schlagen alle Versuche fehl, die Methode Document.browsingTopics() aufzurufen oder eine Anfrage mit einem Sec-Browsing-Topics-Header zu senden, und zwar mit einer NotAllowedError-DOMException.
camera: Steuert, ob das aktuelle Dokument Videoeingabegeräte verwenden darf. Das von getUserMedia() zurückgegebene Promise wird mit einer 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 Promise wird mit einer 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 User-Agent-Daten mit hoher Entropie abzurufen. Wenn die Berechtigung nicht erteilt ist, gibt die Methode nur die Daten mit geringer 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 des Origins der obersten Ebene.
deferred-fetch-minimal: Steuert die Zuweisung des gemeinsamen fetchLater()-Kontingents für Cross-Origin-Subframes.
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 Promise mit einer NotAllowedError-DOMException abgelehnt, falls 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 deaktiviert ist, wird das von Navigator.requestMediaKeySystemAccess() zurückgegebene Promise mit einer SecurityError-DOMException abgelehnt.
fullscreen: Steuert, ob das aktuelle Dokument Element.requestFullscreen() verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das zurückgegebene Promise mit einem TypeError abgelehnt.
gamepad: Steuert, ob das aktuelle Dokument die Gamepad API verwenden darf. Wenn diese Richtlinie deaktiviert ist, lösen Aufrufe von Navigator.getGamepads() eine SecurityError-DOMException aus, und die Ereignisse gamepadconnected und gamepaddisconnected 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 Callbacks dieser Funktionen mit einem GeolocationPositionError-Code von PERMISSION_DENIED aufgerufen werden.
gyroscope: Steuert, ob das aktuelle Dokument über die Gyroscope-Schnittstelle Informationen über die Ausrichtung des Geräts erfassen darf.
hid: Steuert, ob das aktuelle Dokument die WebHID API verwenden darf, um eine Verbindung zu ungewöhnlichen oder exotischen 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 die Idle Detection API verwenden darf, um zu erkennen, wann Benutzer mit ihren Geräten interagieren, beispielsweise um in Chat-Anwendungen den Status „verfügbar“/„abwesend“ zu melden.
language-detector: Steuert den Zugriff auf die Funktionalität zur Spracherkennung der Translator and Language Detector APIs.
language-model: Steuert den Zugriff auf die Prompt API.
local-fonts: Steuert, ob das aktuelle Dokument über die Methode Window.queryLocalFonts() Daten zu den lokal installierten Schriftarten des Benutzers erfassen darf (siehe auch die Local Font Access API).
local-network: Steuert, ob das aktuelle Dokument Netzwerkanfragen an lokale Adressen stellen darf.
local-network-access: Steuert, ob das aktuelle Dokument Netzwerkanfragen an lokale und Loopback-Adressen stellen darf. Diese Richtlinien-Direktive ist ein Alias für die detaillierteren Direktiven local-network und loopback-network.
loopback-network: Steuert, ob das aktuelle Dokument Netzwerkanfragen an Loopback-Adressen stellen darf.
magnetometer: Steuert, ob das aktuelle Dokument über die Magnetometer-Schnittstelle Informationen über die Ausrichtung des Geräts erfassen darf.
microphone: Steuert, ob das aktuelle Dokument Audioeingabegeräte verwenden darf. Wenn diese Richtlinie deaktiviert ist, wird das von MediaDevices.getUserMedia() zurückgegebene Promise mit einer NotAllowedError-DOMException abgelehnt.
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 einer SecurityError-DOMException abgelehnt.
on-device-speech-recognition: Steuert den Zugriff auf die Funktionalität zur Spracherkennung auf dem Gerät der Web Speech API.
otp-credentials: Steuert, ob das aktuelle Dokument die WebOTP API verwenden darf, um ein Einmalkennwort (OTP) aus einer speziell formatierten SMS-Nachricht anzufordern, die vom Server der Anwendung gesendet wurde, d.h. ü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 SecurityError-DOMException aus.
picture-in-picture: Steuert, ob das aktuelle Dokument ein Video über die entsprechende API im Picture-in-Picture-Modus wiedergeben darf.
private-state-token-issuance: Steuert die Verwendung von token-request-Operationen für private state token.
private-state-token-redemption: Steuert die Verwendung von token-redemption- und send-redemption-record-Operationen für private state token.
publickey-credentials-create: Steuert, ob das aktuelle Dokument die Web Authentication API verwenden darf, um neue asymmetrische Schlüssel-Credentials 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-Credentials abzurufen, d.h. über navigator.credentials.get({publicKey: ..., ...}).
screen-wake-lock: Steuert, ob das aktuelle Dokument die Screen Wake Lock API verwenden darf, um anzugeben, dass das Gerät den Bildschirm nicht ausschalten oder abdunkeln 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 Anschluss verbunden sind oder über USB- oder Bluetooth-Geräte, die einen seriellen Anschluss emulieren.
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. in ein <iframe> eingebettet) die Storage Access API verwenden darf, um 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.
unload: Steuert, ob das aktuelle Dokument unload-Event-Handler ausführen darf.
usb: Steuert, ob das aktuelle Dokument die WebUSB API verwenden darf.
web-share: Steuert, ob das aktuelle Dokument Navigator.share() der Web Share API verwenden darf, um Text, Links, Bilder und andere Inhalte an beliebige Ziele nach Wahl des Benutzers zu teilen, zum Beispiel mobile Apps.
window-management: Steuert, ob das aktuelle Dokument die Window Management API verwenden darf, um Fenster auf mehreren Displays 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 Verwendung

Permissions-Policy-Header

Um allen Origins den Zugriff auf Geolocation zu erlauben, würden Sie Folgendes verwenden:

http

Permissions-Policy: geolocation=*

Oder um den Zugriff für eine Teilmenge von Origins zu erlauben, würden Sie Folgendes verwenden:

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 für jede Richtlinie ein separater Header gesendet wird.

Die folgenden Angaben sind beispielsweise 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 für ein <iframe> eine Funktion aktiviert ist, muss sein erlaubter Origin auch in der Allowlist der übergeordneten Seite enthalten sein. Aufgrund dieses Vererbungsverhaltens ist es sinnvoll, im HTTP-Header die weiteste akzeptable Unterstützung für eine Funktion anzugeben und dann in jedem <iframe> die benötigte Teilmenge der Unterstützung festzulegen.

Um allen Origins den Zugriff auf Geolocation zu erlauben, würden Sie Folgendes verwenden:

html

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

Um eine Richtlinie auf den aktuellen Origin und andere anzuwenden, würden Sie Folgendes verwenden:

html

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

Dies ist wichtig: Wenn ein <iframe> standardmäßig zu einem anderen Origin navigiert, wird die Richtlinie nicht auf den Origin angewendet, zu dem das <iframe> navigiert. Indem Sie den Origin, zu dem das <iframe> navigiert, im allow-Attribut aufführen, wird die Permissions Policy, die auf das ursprüngliche <iframe> angewendet wurde, auf den Origin angewendet, zu dem das <iframe> navigiert.

Mehrere Funktionen können gleichzeitig gesteuert werden, indem eine durch Semikolons getrennte Liste von Richtlinien-Direktiven in das allow-Attribut aufgenommen wird.

html

<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 erwähnt, bedeutet die Verwendung dieses Allowlist-Werts, dass die zugehörige Funktion in diesem <iframe> erlaubt wird, sofern das darin geladene Dokument vom selben Origin wie die URL in seinem src-Attribut stammt. Dieser Wert ist der Standardwert für allowlist bei Funktionen, die in allow aufgeführt sind. Daher sind die folgenden Angaben gleichwertig:

html

<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 APIs Microphone (zum Beispiel MediaDevices.getUserMedia()) und Geolocation in seiner Anwendung deaktivieren. Dies kann mit dem folgenden Response-Header erfolgen:

http

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

Durch die Angabe von () für die Origin-Liste werden die angegebenen Funktionen für alle Browsing-Kontexte deaktiviert (einschließlich aller <iframe>s), unabhängig von ihrem Origin.

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

Nehmen wir beispielsweise an, dass wir die Verwendung von Geolocation auf unserem eigenen Origin und in eingebetteten Inhalten unseres vertrauenswürdigen Werbenetzwerks aktivieren möchten. Wir könnten die seitenweite Permissions Policy wie folgt einrichten:

http

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

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

html

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

Wenn ein anderer Origin in <iframe> geladen würde, hätte er keinen Zugriff auf Geolocation:

html

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

Verstöße melden

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

Die folgenden Response-Header blockieren Geolocation und definieren den Namen des Reporting-Endpunkts für die Funktion als „geo_endpoint“. Der HTTP-Response-Header Reporting-Endpoints 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 Berichte über Verstöße an denselben Endpunkt zu senden, könnten wir stattdessen den "default"-Reporting-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, beispielsweise:

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

Die an den Endpunkt gesendete Berichts-Payload könnte 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: Die serverseitige Serialisierung von Verstoßberichten in Chrome verwendet policyId statt featureId für den Funktionsnamen im body eines Serverberichts. Der von einem ReportingObserver zurückgegebene PermissionsPolicyViolationReport entspricht 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