CORS verstehen: Warum Ihre Anfrage fehlgeschlagen ist

Wenn Ihre JavaScript-Anwendung einen CORS-Fehler auslöst, handelt es sich nicht um fehlerhaften Code – es ist der Browser, der Benutzer vor potenziellen Sicherheitsbedrohungen schützt. Um zu verstehen, warum diese Fehler auftreten, muss man das grundlegende Sicherheitsmodell begreifen, das regelt, wie Browser Cross-Origin-Anfragen handhaben.

Die Grundlage der Same-Origin Policy

Browser setzen die Same-Origin Policy als ihren primären Sicherheitsmechanismus durch. Ein Origin besteht aus drei Teilen: Protokoll (https://), Domain (example.com) und Port (:3000). Wenn diese exakt übereinstimmen, fließen Anfragen ungehindert. Wenn sie sich unterscheiden – selbst geringfügig – führen Sie eine Cross-Origin-Anfrage durch.

Betrachten Sie diese Origins:

• https://app.example.com → https://api.example.com (unterschiedliche Subdomain = unterschiedlicher Origin)
• http://localhost:3000 → http://localhost:3001 (unterschiedlicher Port = unterschiedlicher Origin)
• http://example.com → https://example.com (unterschiedliches Protokoll = unterschiedlicher Origin)

Ohne diese Policy könnte jede Website Ihr Gmail lesen, auf Ihre Bankdaten zugreifen oder Anfragen in Ihrem Namen stellen. Cross-Origin Resource Sharing (CORS) bietet eine kontrollierte Lockerung dieser Einschränkungen.

Wie Browser CORS durchsetzen

Der Browser fungiert als Durchsetzer, nicht der Server. Diese Unterscheidung ist wichtig, weil sie gängige Missverständnisse erklärt:

1. „Es funktioniert in Postman/curl” - Diese Tools sind keine Browser; sie setzen CORS nicht durch
2. „Das Hinzufügen des no-cors-Modus wird es beheben” - Dies deaktiviert CORS nicht; es erzeugt eine opake Response, die Sie nicht lesen können
3. „Der Server blockiert meine Anfrage” - Der Server antwortet normal; der Browser blockiert den Zugriff auf die Response

Wenn Sie eine Cross-Origin-Anfrage stellen, fügt der Browser automatisch einen Origin-Header hinzu. Der Server muss mit einem Access-Control-Allow-Origin-Header antworten, der Ihrem Origin entspricht (oder * für öffentliche Ressourcen). Kein übereinstimmender Header bedeutet, dass der Browser den Zugriff auf die Response blockiert – daher Ihr CORS-Fehler.

Einfache vs. Preflight-Anfragen

Nicht alle Anfragen lösen dasselbe CORS-Verhalten aus. Einfache Anfragen werden sofort durchgeführt, während andere eine Preflight-Anfrage erfordern.

Einfache Anfragen (kein Preflight)

Diese Anfragen erfüllen ALLE diese Kriterien:

• Methode: GET, HEAD oder POST
• Header: Nur einfache Header (Accept, Content-Language, Content-Type)
• Content-Type: Nur application/x-www-form-urlencoded, multipart/form-data oder text/plain

Anfragen, die Preflight auslösen

Jede Anfrage, die die einfachen Kriterien nicht erfüllt, löst einen OPTIONS-Preflight aus:

• Methoden wie PUT, DELETE, PATCH
• Benutzerdefinierte Header (Authorization, X-API-Key)
• Content-Type: application/json (ja, JSON löst Preflight aus)

Der Preflight fragt um Erlaubnis, bevor Ihre eigentliche Anfrage gesendet wird. Der Server muss mit entsprechenden Headern antworten:

• Access-Control-Allow-Methods (welche Methoden erlaubt sind)
• Access-Control-Allow-Headers (welche Header zulässig sind)
• Access-Control-Max-Age (wie lange diese Berechtigung gecacht werden soll)

Häufige CORS-Fehlerquellen

Fehlende oder falsche Header

Der Server gibt keinen Access-Control-Allow-Origin-Header zurück, oder er stimmt nicht mit Ihrem Origin überein. Denken Sie daran: http://localhost:3000 und http://localhost:3001 sind unterschiedliche Origins.

Einschränkungen bei Credentials

Das Einbeziehen von Credentials (credentials: 'include' oder withCredentials: true) fügt Einschränkungen hinzu:

• Der Server muss Access-Control-Allow-Credentials: true enthalten
• Access-Control-Allow-Origin kann nicht * sein – es muss Ihren exakten Origin angeben
• Cookies müssen die SameSite-Anforderungen erfüllen

Redirect-Komplikationen

CORS und Redirects interagieren schlecht. Ein Redirect zu einem anderen Origin während einer CORS-Anfrage schlägt oft fehl, weil der Browser den Origin-Wechsel nicht korrekt handhabt. Vermeiden Sie Cross-Origin-Redirects bei CORS-Anfragen.

Private Network Access

Moderne Browser fügen zusätzlichen Schutz hinzu, wenn öffentliche Websites auf private Netzwerkressourcen zugreifen (localhost, 192.168.x.x, 10.x.x.x). Diese Anfragen erfordern möglicherweise zusätzliche Header wie Access-Control-Allow-Private-Network und lösen selbst bei einfachen Anfragen einen Preflight aus. Dieser Schutz verhindert, dass externe Websites Ihr lokales Netzwerk scannen.

CORS effektiv debuggen

Bei CORS-Fehlern:

1. Überprüfen Sie den Netzwerk-Tab des Browsers - Suchen Sie nach der Preflight-OPTIONS-Anfrage und untersuchen Sie sowohl Request- als auch Response-Header
2. Verifizieren Sie die genaue Fehlermeldung - „CORS header ‘Access-Control-Allow-Origin’ missing” vs. „CORS header ‘Access-Control-Allow-Origin’ does not match” weisen auf unterschiedliche Probleme hin
3. Testen Sie zunächst ohne Credentials - Entfernen Sie credentials: 'include', um Credential-bezogene Probleme zu isolieren
4. Bestätigen Sie die Origin-Übereinstimmung - Stellen Sie sicher, dass Protokoll, Domain und Port alle exakt übereinstimmen

Fazit

CORS-Fehler sind keine willkürlichen Hindernisse – sie sind der Browser, der Benutzer vor bösartigen Cross-Origin-Anfragen schützt. Der Server deklariert über CORS-Header, welche Origins auf seine Ressourcen zugreifen können, und der Browser setzt diese Regeln durch. Das Verständnis dieses Modells verwandelt CORS von einem mysteriösen Blocker in ein vorhersehbares System, das Sie methodisch debuggen können.

Wenn Ihre Anfrage fehlschlägt, prüfen Sie, ob es sich um eine einfache oder Preflight-Anfrage handelt, verifizieren Sie, dass die CORS-Header des Servers exakt mit Ihrem Origin übereinstimmen, und denken Sie daran, dass Tools wie Postman diese Prüfungen vollständig umgehen. Der Browser erfüllt seine Aufgabe – Ihre Aufgabe besteht darin, sicherzustellen, dass der Server die korrekten Berechtigungen bereitstellt.

FAQs

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.