Request.credentials — Eigenschaft · JavaScript-Referenz

Signatur

Request.credentials

Beschreibung

Die Eigenschaft credentials eines Request-Objekts gibt den Wert zurück, der beim Erzeugen im Request()-Konstruktor oder in fetch() über die Option credentials festgelegt wurde. Sie bestimmt, ob der Browser Anmeldedaten mitsendet: Cookies, HTTP-Basic-Authentifizierung und TLS-Clientzertifikate. Außerdem legt sie fest, ob Set-Cookie-Header aus der Antwort übernommen werden.

Es gibt drei mögliche Werte:

"omit": Es werden nie Anmeldedaten gesendet, und Cookies aus der Antwort werden verworfen.
"same-origin" (Standard): Anmeldedaten werden nur bei Anfragen an denselben Ursprung (Origin) gesendet.
"include": Anmeldedaten werden immer gesendet, auch bei Cross-Origin-Anfragen.

Die Eigenschaft ist schreibgeschützt. Wer einen anderen Wert braucht, erzeugt mit new Request(bestehenderRequest, { credentials: "include" }) eine Kopie mit geänderter Option. Nützlich ist das Auslesen vor allem in Service Workern, wenn abgefangene Anfragen untersucht oder weitergeleitet werden sollen.

Rückgabewert

Typ

"omit" | "same-origin" | "include"

Beschreibung

Ein String mit der Anmeldedaten-Einstellung der Anfrage. Ohne Angabe ist der Wert "same-origin".

Beispiele

Standardwert auslesen

const req = new Request("/api/profil");
console.log(req.credentials);

same-origin

Cross-Origin-Anfrage mit Cookies

const req = new Request("https://api.example.com/warenkorb", {
  credentials: "include"
});
console.log(req.credentials); // "include"

const ladeWarenkorb = async () => {
  const res = await fetch(req);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
};

ladeWarenkorb().then(console.log).catch(console.error);

include

Service Worker: Anfragen ohne Cookies weiterleiten

// sw.js
self.addEventListener("fetch", (event) => {
  const { request } = event;
  const url = new URL(request.url);

  if (url.pathname.startsWith("/oeffentlich/") && request.credentials !== "omit") {
    // Kopie ohne Anmeldedaten erzeugen
    const anonym = new Request(request, { credentials: "omit" });
    event.respondWith(fetch(anonym));
  }
});

Readonly-Verhalten prüfen

const req = new Request("/daten", { credentials: "omit" });
req.credentials = "include"; // wird still ignoriert (im Strict Mode kein Fehler, da Getter ohne Setter nur im Strict Mode TypeError wirft)
console.log(req.credentials);

omit

// Wichtig · Fallstricke

CORS: Mit credentials: "include" muss der Server Access-Control-Allow-Credentials: true senden. Außerdem darf Access-Control-Allow-Origin dann nicht * sein, sondern muss den konkreten Ursprung nennen. Sonst blockiert der Browser die Antwort.
Sicherheit: "include" sendet Sitzungs-Cookies an fremde Ursprünge. Nutzen Sie diesen Wert nur für vertrauenswürdige Endpunkte und schützen Sie den Server zusätzlich gegen CSRF, zum Beispiel mit SameSite-Cookies oder CSRF-Tokens. Cookies mit SameSite=Lax/Strict werden bei Cross-Site-Anfragen trotz "include" nicht mitgesendet.
Schreibschutz: Eine Zuweisung ändert den Wert nicht. Außerhalb des Strict Mode wird sie still ignoriert, im Strict Mode (z. B. in ES-Modulen) wirft sie einen TypeError. Verwenden Sie stattdessen new Request(req, { credentials }).
Historie: Ältere Browser (vor ca. 2018) nutzten "omit" als Standard für fetch(). Heute ist der Standard überall "same-origin".
Node.js: Die eingebaute fetch-Implementierung (undici) kennt die Eigenschaft, verwaltet aber keine Cookies automatisch. Dort hat der Wert praktisch keine Wirkung.

Siehe auch

Request Request.mode Request.headers Request.prototype.clone() EventSource.withCredentials