HTMLIFrameElement.referrerPolicy — Eigenschaft · JavaScript-Referenz

Signatur

HTMLIFrameElement.referrerPolicy

Beschreibung

Die Eigenschaft referrerPolicy spiegelt das HTML-Attribut referrerpolicy des <iframe>-Elements wider. Sie bestimmt, wie viel von der URL des einbettenden Dokuments im Referer-HTTP-Header mitgeschickt wird, wenn der Browser die Ressource aus src abruft. Das gilt auch für Navigationen, die innerhalb des iframes ausgelöst werden.

Nützlich ist das vor allem beim Einbetten von Inhalten Dritter wie Videos, Karten, Werbung oder Widgets. Dort will man oft nicht, dass Pfade oder Query-Parameter der eigenen Seite nach außen gehen, denn darin können Session-IDs, Suchbegriffe oder interne Strukturen stehen. Mit referrerPolicy kann man die Weitergabe genau steuern.

Erlaubte Werte:

"" (leer): Es gilt die Standard-Richtlinie des Dokuments, meist strict-origin-when-cross-origin.
no-referrer: Es wird nie ein Referrer gesendet.
no-referrer-when-downgrade: Der Referrer wird vollständig gesendet, außer beim Wechsel von HTTPS zu HTTP.
origin: Es wird nur der Ursprung gesendet (Schema, Host, Port).
origin-when-cross-origin: Innerhalb desselben Ursprungs geht die volle URL raus, bei fremden Ursprüngen nur der Ursprung.
same-origin: Der Referrer wird nur an denselben Ursprung gesendet.
strict-origin: Es wird nur der Ursprung gesendet, und das auch nur, wenn das Sicherheitsniveau gleich bleibt.
strict-origin-when-cross-origin: Wie origin-when-cross-origin, aber bei einem Wechsel zu HTTP wird nichts gesendet.
unsafe-url: Die volle URL wird immer gesendet, auch über HTTP. Davon ist abzuraten.

Die Richtlinie wirkt erst bei der nächsten Anfrage. Setzt man sie also, nachdem das iframe schon geladen ist, ändert sich nachträglich nichts. Am besten setzt man sie deshalb vor src oder lädt das iframe danach neu.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen: einer der gültigen Referrer-Policy-Werte, z. B. `"no-referrer"` oder `"origin"`. Ungültige Werte werden beim Lesen als leerer String behandelt.

Rückgabewert

Typ

string

Beschreibung

Die aktuelle Referrer-Richtlinie als String in Kleinbuchstaben. Fehlt das Attribut oder ist sein Wert ungültig, ist das Ergebnis "".

Beispiele

Drittanbieter-iframe ohne Referrer einbetten

const frame = document.createElement('iframe');
// Richtlinie VOR src setzen, damit sie schon für die erste Anfrage gilt
frame.referrerPolicy = 'no-referrer';
frame.src = 'https://example.com/widget';
frame.title = 'Externes Widget';
document.body.append(frame);

console.log(frame.referrerPolicy);
console.log(frame.getAttribute('referrerpolicy'));

no-referrer no-referrer

Bestehende Richtlinie auslesen und ungültige Werte erkennen

// HTML: <iframe id="map" src="https://maps.example.com" referrerpolicy="ORIGIN"></iframe>
//       <iframe id="ad" src="https://ads.example.com" referrerpolicy="foo"></iframe>
const map = document.getElementById('map');
const ad = document.getElementById('ad');

console.log(map.referrerPolicy); // Wert wird normalisiert
console.log(JSON.stringify(ad.referrerPolicy)); // ungültig -> leer

origin ""

Richtlinie nachträglich ändern und iframe neu laden

const frame = document.querySelector('iframe');

const restrictReferrer = (iframe, policy = 'strict-origin') => {
  if (iframe.referrerPolicy === policy) return;
  iframe.referrerPolicy = policy;
  // Die neue Richtlinie gilt erst bei der nächsten Anfrage, darum neu laden
  const url = iframe.src;
  iframe.src = 'about:blank';
  iframe.src = url;
};

restrictReferrer(frame);
console.log(frame.referrerPolicy);

strict-origin

Alle externen iframes pauschal absichern

document.querySelectorAll('iframe[src]').forEach((iframe) => {
  const { origin } = new URL(iframe.src, location.href);
  if (origin !== location.origin && !iframe.referrerPolicy) {
    iframe.referrerPolicy = 'origin';
  }
});

// Wichtig · Fallstricke

Zeitpunkt: Die Richtlinie gilt nur für Anfragen, die nach dem Setzen gestartet werden. Wenn man sie nach src setzt, gilt sie für die erste Anfrage meist nicht mehr, denn die Anfrage kann schon laufen.
Vorrang: Das Attribut am Element hat Vorrang vor der Richtlinie des Dokuments, also dem Referrer-Policy-HTTP-Header oder <meta name="referrer">. Ein leerer Wert fällt auf die Richtlinie des Dokuments zurück.
Standardwert: Moderne Browser verwenden strict-origin-when-cross-origin, wenn nichts angegeben ist. Ältere Browser nutzten no-referrer-when-downgrade.
Datenschutz/Sicherheit: Mit unsafe-url können sensible URL-Bestandteile wie Tokens oder Suchparameter an Dritte und über unverschlüsselte Verbindungen abfließen. Das sollte man vermeiden. Umgekehrt kann no-referrer Anbieter stören, die per Referrer prüfen, von welcher Domain eingebettet wird. Einige Video- oder Kartendienste verlangen mindestens origin.
Kein Ersatz für Isolation: referrerPolicy steuert nur den Referrer. Für echte Isolation von Fremdinhalten zusätzlich sandbox und allow nutzen.
Kompatibilität: Wird in allen aktuellen Browsern (Chrome, Edge, Firefox, Safari) unterstützt. Der Internet Explorer unterstützt die Eigenschaft nicht.

Siehe auch

Document.referrer HTMLIFrameElement.featurePolicy HTMLIFrameElement.browsingTopics HTMLIFrameElement.credentialless HTMLIFrameElement.srcdoc