HTMLIFrameElement.csp — Eigenschaft · JavaScript-Referenz

Signatur

HTMLIFrameElement.csp

Beschreibung

Die Eigenschaft csp spiegelt das HTML-Attribut csp eines <iframe>-Elements wider. Sie gehört zur Spezifikation CSP Embedded Enforcement. Damit kann die einbettende Seite eine Mindest-Sicherheitsrichtlinie festlegen, an die sich das eingebettete Dokument halten muss, zum Beispiel script-src 'self' oder object-src 'none'.

Wenn das Attribut gesetzt ist, schickt der Browser bei der Navigation im Frame den Request-Header Sec-Required-CSP mit der geforderten Richtlinie an den Server. Das eingebettete Dokument wird nur dargestellt, wenn der Server zustimmt. Das geht auf zwei Wegen:

Der Server liefert eine eigene Content-Security-Policy, die mindestens so streng ist wie die geforderte Richtlinie (sie umfasst sie).
Der Server erlaubt der einbettenden Origin mit dem Antwort-Header Allow-CSP-From, ihm eine Richtlinie vorzugeben.

Stimmt der Server nicht zu, blockiert der Browser das Dokument und zeigt stattdessen eine Fehlerseite im Frame. Nützlich ist das vor allem für Plattformen, die fremde Inhalte einbetten, etwa Widgets, Werbung oder Drittanbieter-Integrationen. Sie wollen sicherstellen, dass diese Inhalte zum Beispiel keine Inline-Skripte ausführen.

Der Wert ist ein String mit einer gewöhnlichen CSP-Richtlinie. Bei mehreren Direktiven werden sie wie im Header mit Semikolon getrennt. Ohne Attribut ist der Wert ein leerer String.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Nur beim Setzen: eine CSP-Richtlinie, z. B. `"script-src 'self'; object-src 'none'"`. Der Wert wird in das HTML-Attribut `csp` geschrieben.

Rückgabewert

Typ

string

Beschreibung

Die aktuell im Attribut csp hinterlegte Richtlinie oder ein leerer String, wenn keine gesetzt ist. In nicht unterstützenden Browsern ist die Eigenschaft undefined.

Beispiele

Drittanbieter-Widget mit geforderter CSP einbetten

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

// Richtlinie VOR dem Setzen von src festlegen,
// sonst wird der Header Sec-Required-CSP bei der ersten Navigation nicht gesendet
frame.csp = "script-src 'self'; object-src 'none'; base-uri 'none'";
frame.src = 'https://widget.example.com/embed';
frame.title = 'Wetter-Widget';

document.body.append(frame);
console.log(frame.getAttribute('csp'));

script-src 'self'; object-src 'none'; base-uri 'none'

Feature-Erkennung mit Fallback auf sandbox

const embedSafely = (url, policy) => {
  const frame = document.createElement('iframe');

  if ('csp' in HTMLIFrameElement.prototype) {
    frame.csp = policy;
  } else {
    // Fallback: Rechte über sandbox einschränken
    frame.sandbox = 'allow-scripts';
    console.warn('CSP Embedded Enforcement wird nicht unterstützt');
  }

  frame.src = url;
  document.body.append(frame);
  return frame;
};

embedSafely('https://ads.example.net/slot/42', "default-src 'self'");

In Firefox/Safari: "CSP Embedded Enforcement wird nicht unterstützt"

Vorhandene Richtlinie auslesen und verschärfen

// HTML: <iframe id="partner" csp="script-src 'self'" src="https://partner.example.org/"></iframe>
const frame = document.querySelector('#partner');

console.log(frame.csp);

// Weitere Direktive ergänzen und Frame neu laden,
// damit die neue Richtlinie beim Server ankommt
frame.csp = `${frame.csp}; frame-ancestors 'self'`;
frame.src = frame.src;

script-src 'self'

Serverseitige Zustimmung (Node.js/Express)

import express from 'express';

const app = express();

app.get('/embed', (req, res) => {
  const required = req.get('Sec-Required-CSP');
  console.log('Geforderte CSP:', required);

  // Der einbettenden Origin erlauben, eine CSP vorzugeben
  res.set('Allow-CSP-From', 'https://portal.example.com');
  res.send('<p>Eingebetteter Inhalt</p>');
});

app.listen(3000);

Geforderte CSP: script-src 'self'; object-src 'none'

// Wichtig · Fallstricke

Experimentell und nur eingeschränkt verfügbar: Nur Chromium-basierte Browser (Chrome, Edge, Opera) unterstützen csp. Firefox und Safari ignorieren das Attribut, der Frame lädt dort also ohne die geforderte Richtlinie. Verlass dich deshalb nicht allein darauf, sondern kombiniere es mit sandbox, allow und einer eigenen CSP.

Reihenfolge beachten: Setze csp vor src. Eine spätere Änderung wirkt erst bei der nächsten Navigation des Frames.
Server muss mitspielen: Wenn die Antwort weder Allow-CSP-From noch eine CSP liefert, die die geforderte Richtlinie umfasst, wird der Inhalt blockiert. Das passiert oft unerwartet bei fremden Anbietern.
Der Wert muss eine syntaktisch gültige Richtlinie sein. Ungültige Werte, zum Beispiel mit Zeilenumbrüchen oder Kommas, führen in Chromium dazu, dass das Attribut verworfen wird.
Die Richtlinie gilt auch für verschachtelte Frames innerhalb des eingebetteten Dokuments.
Kein Ersatz für serverseitige Sicherheit: csp schützt die einbettende Seite nicht vor bösartigen Inhalten, wenn der Browser das Feature nicht unterstützt. Zum Schutz vor XSS in der eigenen Seite brauchst du weiterhin einen eigenen Content-Security-Policy-Header.

Siehe auch

HTMLBaseElement.href HTMLFormElement.rel HTMLIFrameElement.src HTMLIFrameElement.name HTMLIFrameElement.allow