Der HTTPPermissions-PolicyResponse-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.

Weitere Informationen finden Sie im Hauptartikel zurPermissions Policy.

Syntax

Permissions-Policy: <directive>=<allowlist>

<directive>

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

<allowlist>

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

* (Wildcard)

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

() (leere Allowlist)

Die Funktion ist in top-level 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 in Cross-Origin-Dokumenten in verschachtelten Browsing-Kontexten nicht erlaubt.self kann als Kurzform fürhttps://your-site.example.com angesehen werden. Das Äquivalent für<iframe>-allow-Attribute istself.

src

Die Funktion wird in diesem<iframe> erlaubt, solange das Dokument in demselben Ursprung wie die URL in seinemsrc-Attribut geladen wird. Dieser Wert wird nur im<iframe>-allow-Attribut verwendet und ist derdefaultallowlist-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 allein verwendet werden, währendself undsrc in Kombination mit einem oder mehreren Ursprüngen verwendet werden können.

Hinweis:Direktiven haben eine standardmäßige Allowlist, die immer entweder*,self odernone für denPermissions-Policy-HTTP-Header ist und das Standardverhalten steuert, wenn sie nicht explizit in einer Policy aufgeführt sind.Diese sind auf den einzelnenDirektivreferenzseiten spezifiziert. Für<iframe>-allow-Attribute ist das Standardverhalten immersrc.

Wenn unterstützt, können Sie in Permissions Policy-Ursprüngen Wildcards einfügen. Dies bedeutet, dass Sie anstelle mehrerer verschiedener Subdomains in einer Allowlist alle in einem einzigen Ursprung mit einem Wildcard angeben können.

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

Direktiven

accelerometerExperimentell

Steuert, ob das aktuelle Dokument erlaubt ist, Informationen über die Beschleunigung des Geräts über dieAccelerometer-Schnittstelle zu sammeln.

ambient-light-sensorExperimentell

Steuert, ob das aktuelle Dokument berechtigt ist, Informationen über die Lichtmenge in der Umgebung des Geräts über dieAmbientLightSensor-Schnittstelle zu sammeln.

aria-notifyExperimentellNicht standardisiert

Steuert, ob das aktuelle Dokument dieariaNotify()-Methode verwenden darf, umScreenreader-Ankündigungen auszulösen.

attribution-reportingExperimentell

Steuert, ob das aktuelle Dokument dieAttribution Reporting API verwenden darf.

autoplayExperimentell

Steuert, ob das aktuelle Dokument Medienautoplay über dieHTMLMediaElement-Schnittstelle erlauben darf. Wenn diese Richtlinie deaktiviert ist und es keine Benutzeraktionen gab, wird dasPromise, das vonHTMLMediaElement.play() zurückgegeben wird, mit einemNotAllowedError-DOMException abgelehnt. Das Autoplay-Attribut für<audio>- und<video>-Elemente wird ignoriert.

bluetoothExperimentell

Steuert, ob die Verwendung derWeb Bluetooth API erlaubt ist. Wenn diese Richtlinie deaktiviert ist, geben die Methoden desBluetooth-Objekts, das vonNavigator.bluetooth zurückgegeben wird, entwederfalse zurück oder lehnen das zurückgegebenePromise mit einemSecurityError-DOMException ab.

browsing-topicsExperimentellNicht standardisiert

Steuert den Zugang zurTopics API. Wenn eine Richtlinie die Verwendung der Topics API speziell nicht erlaubt, schlagen alle Versuche, dieDocument.browsingTopics()-Methode aufzurufen oder eine Anfrage mit einemSec-Browsing-Topics-Header zu senden, mit einemNotAllowedError-DOMException fehl.

cameraExperimentell

Steuert, ob das aktuelle Dokument Videogeräte verwenden darf. Das vongetUserMedia() zurückgegebenePromise wird mit einemNotAllowedError-DOMException abgelehnt, wenn die Erlaubnis nicht erteilt wird.

captured-surface-controlExperimentell

Steuert, ob das Dokument die Verwendung derCaptured Surface Control API erlaubt ist.Das von den Hauptmethoden der API zurückgegebene Promise wird mit einemNotAllowedError-DOMException abgelehnt, wenn die Erlaubnis nicht erteilt wird.

compute-pressureExperimentell

Steuert den Zugang zurCompute Pressure API.

cross-origin-isolatedExperimentell

Steuert, ob das aktuelle Dokument alscross-origin isoliert behandelt werden kann.

deferred-fetchExperimentell

Steuert die Zuweisung desfetchLater()-Kontingents des Top-Level-Ursprungs.

deferred-fetch-minimalExperimentell

Steuert die Zuweisung des geteilten kontingentierten Cross-Origin-SubframefetchLater()-Kontingents.

display-captureExperimentell

Steuert, ob das aktuelle Dokument die Verwendung dergetDisplayMedia()-Methode zur Bildschirmaufnahme erlaubt ist. Wenn diese Richtlinie deaktiviert ist, wird das vongetDisplayMedia() zurückgegebene Promise mit einemNotAllowedError-DOMException abgelehnt, wenn die Erlaubnis zur Bildschirmaufnahme nicht erteilt wird.

encrypted-mediaExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derEncrypted Media Extensions API (EME) erlaubt ist. Wenn diese Richtlinie deaktiviert ist, wird das vonNavigator.requestMediaKeySystemAccess() zurückgegebenePromise mit einemSecurityError-DOMException abgelehnt.

fullscreenExperimentell

Steuert, ob das aktuelle Dokument die Verwendung vonElement.requestFullscreen() erlaubt ist. Wenn diese Richtlinie deaktiviert ist, wird das zurückgegebenePromise mit einemTypeError abgelehnt.

gamepadExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derGamepad API erlaubt ist.Wenn diese Richtlinie deaktiviert ist, werfen Aufrufe vonNavigator.getGamepads() einenSecurityError-DOMException, und diegamepadconnected undgamepaddisconnected-Ereignisse werden nicht ausgelöst.

geolocationExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derGeolocation-Schnittstelle erlaubt ist. Wenn diese Richtlinie deaktiviert ist, verursachen Aufrufe vongetCurrentPosition() undwatchPosition(), dass deren Rückruffunktionen mit einemGeolocationPositionError-Code vonPERMISSION_DENIED aufgerufen werden.

gyroscopeExperimentell

Steuert, ob das aktuelle Dokument berechtigt ist, Informationen über die Orientierung des Geräts über dieGyroscope-Schnittstelle zu sammeln.

hidExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derWebHID API zur Verbindung mit seltenen oder exotischen Benutzerschnittstellengeräten wie alternativen Tastaturen oder Gamepads erlaubt ist.

identity-credentials-getExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derFederated Credential Management API (FedCM) erlaubt ist.

idle-detectionExperimentell

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

language-detectorExperimentell

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

local-fontsExperimentell

Steuert, ob das aktuelle Dokument die Sammlung von Daten über die lokal installierten Schriften des Benutzers über dieWindow.queryLocalFonts()-Methode erlaubt ist (siehe auch dieLocal Font Access API).

magnetometerExperimentell

Steuert, ob das aktuelle Dokument berechtigt ist, Informationen über die Orientierung des Geräts über dieMagnetometer-Schnittstelle zu sammeln.

microphoneExperimentell

Steuert, ob das aktuelle Dokument die Verwendung von Audioeingabegeräten erlaubt ist. Wenn diese Richtlinie deaktiviert ist, wird das vonMediaDevices.getUserMedia() zurückgegebenePromise mit einemNotAllowedError-DOMException abgelehnt.

midiExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derWeb MIDI API erlaubt ist. Wenn diese Richtlinie deaktiviert ist, wird das vonNavigator.requestMIDIAccess() zurückgegebenePromise mit einemSecurityError-DOMException abgelehnt.

on-device-speech-recognitionExperimentell

Steuert den Zugriff auf dieOn-Device-Spracherkennung derWeb Speech API.

otp-credentialsExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derWebOTP API erlaubt ist, um ein Einmal-Passwort (OTP) aus einer speziell formatierten SMS-Nachricht anzufordern, die von einem Server der App gesendet wurde, d.h. übernavigator.credentials.get({otp: ..., ...}).

paymentExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derPayment Request API erlaubt ist. Wenn diese Richtlinie aktiviert ist, wird derPaymentRequest()-Konstruktor einenSecurityError-DOMException werfen.

picture-in-pictureExperimentell

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

publickey-credentials-createExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derWeb Authentication API zur Erstellung neuer asymmetrischer Schlüsselanmeldeinformationen erlaubt ist, d.h. übernavigator.credentials.create({publicKey: ..., ...}).

publickey-credentials-getExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derWeb Authentication API zum Abrufen bereits gespeicherter öffentlicher Schlüsselanmeldeinformationen erlaubt ist, d.h. übernavigator.credentials.get({publicKey: ..., ...}).

screen-wake-lockExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derScreen Wake Lock API zur Angabe, dass das Gerät den Bildschirm nicht ausschalten oder dimmen soll, erlaubt ist.

serialExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derWeb Serial API zur Kommunikation mit seriellen Geräten, entweder direkt über einen seriellen Anschluss oder über USB- oder Bluetooth-Geräte, die einen seriellen Anschluss emulieren, erlaubt ist.

speaker-selectionExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derAudio Output Devices API zur Auflistung und Auswahl von Lautsprechern erlaubt ist.

storage-accessExperimentell

Steuert, ob ein in einem Drittanbieter-Kontext geladenes Dokument (d.h. eingebettet in ein<iframe>) die Verwendung derStorage Access API zur Anforderung des Zugriffs auf unpartitionierte Cookies erlaubt ist.

translatorExperimentell

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

summarizerExperimentell

Steuert den Zugriff auf dieSummarizer API.

usbExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derWebUSB API erlaubt ist.

web-shareExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derNavigator.share() derWeb Share API erlaubt ist, um Text, Links, Bilder und andere Inhalte an beliebige Ziele der Wahl des Benutzers zu teilen, z.B. mobile Apps.

window-managementExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derWindow Management API zur Verwaltung von Fenstern auf mehreren Anzeigen erlaubt ist.

xr-spatial-trackingExperimentell

Steuert, ob das aktuelle Dokument die Verwendung derWebXR Device API zur Interaktion mit einer WebXR-Sitzung erlaubt ist.

Beispiele

Grundlegende Verwendung

Permissions-Policy-Header

Um allen Ursprüngen den Zugang zur Geolokalisierung zu erlauben, würden Sie dies tun:

Permissions-Policy: geolocation=*

Oder um den Zutritt zu einem Teilset 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 Komma 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 der erlaubte Ursprung auch in der Allowlist der übergeordneten Seite sein. Aufgrund diesesVererbungsverhaltens ist es eine gute Idee, die weitestgehend akzeptable Unterstützung für eine Funktion im HTTP-Header festzulegen und dann den benötigten Teilset der Unterstützung in jedem<iframe> zu spezifizieren.

Um allen Ursprüngen den Zugang zur Geolokalisierung 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>

Das ist wichtig: Wenn ein<iframe> standardmäßig zu einem anderen Ursprung navigiert, wird die Richtlinie nicht auf den Ursprung angewendet, zu dem das<iframe> navigiert. Durch die Angabe des Ursprungs, zu dem das<iframe> imallow-Attribut navigiert, wird die auf das ursprüngliche<iframe> angewendete Permissions Policy auf den Ursprung angewendet, zu dem das<iframe> navigiert.

Mehrere Funktionen können gleichzeitig gesteuert werden, indem eine durch Semikolons separierte Liste von Richtliniendirektiven innerhalb desallow-Attributs eingefügt wird.

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

Es lohnt sich, demsrc-Wert eine besondere Erwähnung zu geben. Wie oben erwähnt, bedeutet die Verwendung dieses Allowlist-Wertes, dass die zugehörige Funktion in diesem<iframe> erlaubt wird, solange das Dokument, das in es geladen wird, aus demselben Ursprung wie die URL in seinemsrc-Attribut stammt. Dieser Wert ist derdefaultallowlist-Wert für inallow aufgelistete Funktionen, sodass die folgenden gleichwertig sind:

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

Zugangsverweigerung zu leistungsstarken Funktionen

SecureCorp Inc. möchte die Mikrofon- (z. B.MediaDevices.getUserMedia()) undGeolocation-APIs in ihrer Anwendung deaktivieren. Dies kann über den folgenden Response-Header erfolgen:

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

Durch die Angabe von() für die Ursprungslist werden die angegebenen Funktionen für alle Browsing-Kontexte (dazu gehören alle<iframe>s) unabhängig von ihrem Ursprung deaktiviert.

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

Nehmen wir zum Beispiel an, dass wir die Geolokalisierungsnutzung in unserem eigenen Ursprung und in eingebettetem Inhalt von unserem vertrauenswürdigen Ad-Netzwerk ermöglichen möchten. Wir könnten die seitenweite Permissions Policy wie folgt einrichten:

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

In unseren Ad-<iframe>s könnten wir den Zugriff auf denhttps://trusted-ad-network.com-Ursprung so festlegen:

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

Wenn ein anderer Ursprung in<iframe> geladen wird, hätte er keinen Zugang zur Geolokalisierung:

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Permissions Policy
• Document.featurePolicy undFeaturePolicy
• Content-Security-Policy
• Referrer-Policy