EventSource.withCredentials — Eigenschaft · JavaScript-Referenz

Signatur

EventSource.withCredentials

Beschreibung

Die Eigenschaft withCredentials einer EventSource-Instanz zeigt an, ob die Verbindung zum Server-Sent-Events-Endpunkt bei Cross-Origin-Anfragen Zugangsdaten mitsendet. Dazu gehören Cookies, HTTP-Authentifizierung und TLS-Client-Zertifikate. Der Wert kommt aus dem Optionsobjekt des Konstruktors: new EventSource(url, { withCredentials: true }).

Die Eigenschaft ist schreibgeschützt. Nach dem Erzeugen lässt sich der Wert nicht mehr ändern. Wer andere Einstellungen braucht, schließt die Verbindung mit close() und legt eine neue EventSource an. Ohne Angabe ist der Wert false. Der Browser nutzt dann den Credentials-Modus same-origin: Anfragen an denselben Ursprung enthalten Cookies, Anfragen an fremde Ursprünge nicht.

Praktisch nutzt man die Eigenschaft vor allem zur Fehlersuche und Protokollierung. So lässt sich prüfen, ob eine Verbindung wirklich mit Zugangsdaten aufgebaut wurde, etwa wenn ein SSE-Dienst unter einer eigenen Subdomain (events.example.com) läuft und eine Sitzung über Cookies erkennen soll.

Beispiele

Wert nach der Instanziierung auslesen

// Ohne Optionen: Standardwert false
const lokal = new EventSource('/api/stream');
console.log(lokal.withCredentials);

// Mit Zugangsdaten für eine andere Origin
const extern = new EventSource('https://events.example.com/stream', {
  withCredentials: true
});
console.log(extern.withCredentials);

false true

Cookie-basierte Sitzung mit einer Subdomain

const source = new EventSource('https://events.example.com/notifications', {
  withCredentials: true
});

source.addEventListener('open', () => {
  console.log(`Verbunden (Zugangsdaten: ${source.withCredentials})`);
});

source.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  console.log('Neue Benachrichtigung:', data.title);
});

source.addEventListener('error', () => {
  if (source.readyState === EventSource.CLOSED) {
    console.warn('Verbindung abgelehnt – CORS-Header am Server prüfen.');
  }
});

Verbunden (Zugangsdaten: true) Neue Benachrichtigung: Neue Nachricht von Anna

Schreibschutz: Neu verbinden statt umschalten

let source = new EventSource('https://events.example.com/stream');

// Zuweisung wird ignoriert (im Strict Mode: TypeError)
try {
  'use strict';
  source.withCredentials = true;
} catch (e) {
  console.log('Nicht änderbar:', e.constructor.name);
}
console.log(source.withCredentials);

// Richtig: alte Verbindung schließen, neue mit Option anlegen
const reconnectWithCredentials = (old) => {
  old.close();
  return new EventSource(old.url, { withCredentials: true });
};

source = reconnectWithCredentials(source);
console.log(source.withCredentials);

false true

// Wichtig · Fallstricke

Serverseitige CORS-Header sind Pflicht: Bei withCredentials: true muss der Server Access-Control-Allow-Origin mit der genauen Origin senden (kein *) und zusätzlich Access-Control-Allow-Credentials: true. Fehlt einer der Header, bricht der Browser die Verbindung ab und löst ein error-Event aus. Die readyState ist dann CLOSED, und es gibt keine automatische Neuverbindung.
Schreibgeschützt: Eine Zuweisung hat keine Wirkung. Im Strict Mode wirft sie einen TypeError. Der Wert lässt sich nur über den Konstruktor festlegen.
Sicherheit: Wenn Cookies mitgesendet werden, ist der Endpunkt anfällig für Cross-Site-Angriffe, sobald der Server beliebige Origins zurückspiegelt. Erlaubte Origins deshalb serverseitig über eine Whitelist prüfen. Außerdem können Cookie-Attribute wie SameSite sowie Tracking-Schutz oder das Blockieren von Drittanbieter-Cookies im Browser verhindern, dass Cookies trotz withCredentials mitgesendet werden.
Keine eigenen Header: Die EventSource-API kann keine eigenen Header wie Authorization: Bearer … setzen. Für tokenbasierte Authentifizierung braucht man Cookies, Token als Query-Parameter (Vorsicht: sie landen in Logs) oder eine Umsetzung mit fetch() und ReadableStream.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Der Internet Explorer kennt EventSource überhaupt nicht. In Web Workern ist die Eigenschaft ebenfalls verfügbar.

Siehe auch

EventSource EventSource.url EventSource.readyState EventSource.prototype.close() XMLHttpRequest.withCredentials Request.credentials