🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🌐 धडा 09 — CORS: browser आधी विचारतो

📍 तुम्ही इथे आहात: 12 पैकी धडा 09 · मागे: lesson-08-caching · पुढे: lesson-10-custom-domains

📦 या ब्रँचमध्ये काय आहे

धडे 01–08, आणि CORS: browser आधी पाठवतो ती preflight OPTIONS request, office उत्तरात देते ते Access-Control-Allow-* headers, आणि CORS तुमच्या API चे नाही तर browsers चे संरक्षण का करते. apigw/demo.py मधले cors() शाळेच्या स्वतःच्या web site कडून आणि एका अनोळखी site कडून आलेल्या preflight ला उत्तर देते.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

पालकांचा browser 🌐 हा अतिशय काळजीपूर्वक वागणारा मदतनीस आहे. पालक शाळेचे web page, https://school.example, वाचत आहेत. ते page browser ला विचारते: "कृपया ऐश्वर्याचे गुण https://api.school.example वरून आणून दे". तो दुसरा पत्ता आहे.

म्हणून browser आधी office च्या दारावर टकटक करतो आणि विचारतो: "school.example वरच्या page ला GET पाठवायचा आहे. चालेल का?" ही टकटक म्हणजे preflight (OPTIONS).

Clerk उत्तर देतो: "हो — school.example साठी, या methods, हे headers, आणि हे उत्तर तू 10 मिनिटे लक्षात ठेवू शकतोस." मग browser खरी request पाठवतो.

evil.example वरचे एक page तेच विचारते. Clerk नाही म्हणतो. मग browser त्या page ला उत्तर द्यायला नकार देतो.

लक्ष द्या: आज्ञा पाळतो तो browser. curl वापरणारी व्यक्ती कधीच आधी विचारत नाही — clerk चे "नाही" तिला थांबवत नाही.

🗺️ आकृती

sequenceDiagram
    participant P as 📄 page on school.example
    participant B as 🌐 browser
    participant O as 🛎️ front office
    P->>B: fetch api/students/7
    B->>O: OPTIONS /students/7 · Origin: https://school.example
    O-->>B: 204 · Allow-Origin: https://school.example · Max-Age: 600
    B->>O: GET /students/7 · Origin: https://school.example
    O-->>B: 200 · Access-Control-Allow-Origin: https://school.example
    B-->>P: the answer
    Note over B,O: Origin https://evil.example → 403, and the browser blocks the page

🗺️ काढलेली आकृती + एक lab: https://school-edh.pages.dev/apigateway/lesson-diagrams.html#l09

❓ काय

Origin — page चे scheme + host + port: https://school.example. http://school.example हा वेगळा origin आहे.
Same-origin policy — browser चा नियम: दुसऱ्या origin ने परवानगी दिल्याशिवाय page त्या origin कडची उत्तरे वाचू शकत नाही. CORS (Cross-Origin Resource Sharing) ही परवानगी देण्याची पद्धत आहे.
Preflight — "non-simple" requests साठी (उदा. JSON bodies, Authorization header, PUT/DELETE), browser आधी Origin, Access-Control-Request-Method आणि Access-Control-Request-Headers सह OPTIONS पाठवतो.
उत्तराचे headers — Access-Control-Allow-Origin (एक origin, किंवा *), Access-Control-Allow-Methods, Access-Control-Allow-Headers, Access-Control-Max-Age (browser उत्तर किती काळ लक्षात ठेवू शकतो), आणि Access-Control-Allow-Credentials (cookies; मग origin * असू शकत नाही).
खऱ्या response लाही header हवा — Access-Control-Allow-Origin प्रत्यक्ष GET/POST उत्तरावरही असायला हवा, error उत्तरांसह, नाहीतर page ते वाचू शकत नाही.
API Gateway मध्ये — HTTP APIs: एकच corsConfiguration, आणि office preflights ना स्वतःच उत्तर देते. REST APIs: एक OPTIONS method (सहसा mock integration) headers परत देते; proxy integration असेल तर तुमच्या back end ने स्वतःच्या responses मध्ये Access-Control-Allow-Origin घालायला हवा; headers gateway responses (DEFAULT_4XX, DEFAULT_5XX) मध्येही घाला, म्हणजे browser pages errors वाचू शकतील.

🤔 का

कारण जवळजवळ प्रत्येक web app दुसऱ्या origin वरचा API call करते, आणि header नसणे हा सगळ्यात सामान्य "curl मध्ये चालते पण browser मध्ये नाही" bug आहे. आणि कारण अनेकांना वाटते की CORS ही API साठी security भिंत आहे. तसे नाही: ती user च्या browser चे अशा pages पासून संरक्षण करते जी user च्या cookies वापरून data वाचायचा प्रयत्न करतात. तुमच्या API ला auth लागतोच (धडा 06).

🔧 कसे (या repo मध्ये)

apigw/gateway.py मधला Gateway._handle() प्रत्येक OPTIONS ला route matching च्या आधीच स्वतः उत्तर देतो (HTTP API च्या CORS setting प्रमाणे): cors_origins मधल्या origin ला चार Access-Control-* headers सह 204 मिळतो; इतर कोणत्याही origin ला 403 CORS origin not allowed मिळतो. Request चा Origin परवानगी असलेला असेल तेव्हा Gateway.handle() खऱ्या उत्तरातही Access-Control-Allow-Origin घालतो. office() नेमका एकच origin परवानगी देतो: https://school.example.

🧪 करून पाहा

python3 apigw/demo.py cors
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office
gw, _ = office()
for origin in ("https://school.example", "http://school.example", "https://school.example.evil.com"):
    st, hd, _ = gw.handle("OPTIONS", "/marks", {"Origin": origin, "Access-Control-Request-Method": "POST"})
    print(st, origin, hd.get("Access-Control-Allow-Origin"))
st, hd, out = gw.handle("GET", "/students/9", {"Origin": "https://evil.example"})
print("GET from evil.example:", st, out, "· Allow-Origin header:", hd.get("Access-Control-Allow-Origin"))
EOF

चालू office वर तुम्हीच browser बना:

python3 apigw/demo.py serve &
sleep 1                                # give the office a second to open
curl -i -X OPTIONS -H "Origin: https://school.example" -H "Access-Control-Request-Method: GET" localhost:8080/students/7
curl -i -X OPTIONS -H "Origin: https://evil.example" localhost:8080/students/7
curl -i -H "Origin: https://evil.example" localhost:8080/students/9
kill %1

✅ तपासा — तुम्हाला काय दिसायला हवे

cors छापते OPTIONS /students/7 → 204 Access-Control-Allow-Origin: https://school.example Access-Control-Allow-Methods: GET,POST,PUT,DELETE Access-Control-Allow-Headers: authorization,content-type,x-api-key Access-Control-Max-Age: 600, मग https://evil.example साठी OPTIONS /students/7 → 403 {'message': 'CORS origin not allowed'}, मग X-Cache: Miss Access-Control-Allow-Origin: https://school.example सह खरा GET.

तुमचा snippet छापतो 204 https://school.example https://school.example, 403 http://school.example None (वेगळा scheme म्हणजे वेगळा origin) आणि 403 https://school.example.evil.com None (सारखे दिसणारे नाव म्हणजे तोच origin नाही). शेवटची ओळ सगळ्यात महत्त्वाची आहे: GET from evil.example: 200 {'id': '9', 'name': 'Katrina', 'class': '9A'} · Allow-Origin header: None — office ने उत्तर दिलेच; फक्त browser ते उत्तर page पासून लपवेल.

चालू office वर: चार Access-Control-* headers सह HTTP/1.0 204 No Content; {"message": "CORS origin not allowed"} सह HTTP/1.0 403 Forbidden; आणि evil.example कडून आलेल्या साध्या GET साठी data सह HTTP/1.0 200 OK, पण Access-Control-Allow-Origin header नाही.

🏁 तुम्ही आत्ताच काय सिद्ध केले

तुम्ही browser प्रमाणे preflight वाचू शकता, आणि तुम्ही स्वतःच्या डोळ्यांनी पाहिले की CORS curl ला थांबवत नाही — तो browsers पाळतात तो नियम आहे, API वरचे कुलूप नाही.

⚠️ नेहमीच्या चुका

credentials (cookies) सोबत Access-Control-Allow-Origin: * — browsers ते नाकारतात
CORS headers OPTIONS उत्तरावर आहेत पण खऱ्या response वर नाहीत (किंवा 4XX/5XX errors वर नाहीत)
"school.example ने संपतो" असे origins जुळवणे — evil-school.example पास होतो; नेमके origins यादीत लिहा
खऱ्या auth समस्येवर CORS रुंद करून "उपाय" करणे — CORS म्हणजे auth नाही
Allow-Headers मध्ये authorization विसरणे, त्यामुळे token असलेली प्रत्येक request preflight मध्येच अपयशी ठरते

🏭 प्रत्यक्ष वापरात

खऱ्या account वर — HTTP API वर CORS म्हणजे एकच setting:

aws apigatewayv2 update-api --api-id a1b2c3 --cors-configuration \
    AllowOrigins=https://school.example,AllowMethods=GET,POST,AllowHeaders=authorization,content-type,MaxAge=600

REST API वर, browser pages ना office चे स्वतःचे errors सुद्धा वाचू द्या:

cat > cors-4xx.json <<'EOF'
{ "gatewayresponse.header.Access-Control-Allow-Origin": "'https://school.example'" }
EOF
aws apigateway put-gateway-response --rest-api-id abc123 --response-type DEFAULT_4XX \
    --response-parameters file://cors-4xx.json

(आतले single quotes आवश्यक आहेत: ते value ठरलेली (fixed) आहे, variable नाही हे दाखवतात.)

आणि Lambda proxy back end स्वतःच्या उत्तरांमध्ये header घालतो:

return {"statusCode": 200,
        "headers": {"Access-Control-Allow-Origin": "https://school.example"},
        "body": json.dumps(student)}

🏭 Production मध्ये हे का महत्त्वाचे आहे: प्रत्येक stage साठी नेमके origins यादीत लिहा (dev web site आणि prod web site वेगळ्या आहेत), errors वरही headers घाला, आणि CORS ला कधीही authorizer चा पर्याय मानू नका.

⏭️ पुढे

Browsers खूश आहेत. पण पत्ता अजूनही abc123.execute-api.ap-south-1.amazonaws.com आहे. Office ला नावफलक द्या — custom domains आणि TLS.

git checkout lesson-10-custom-domains

🌐 Lesson 09 — CORS: the browser asks first

📍 You are here: Lesson 09 of 12 · Previous: lesson-08-caching · Next: lesson-10-custom-domains

📦 What's in this branch

Lessons 01–08, plus CORS: the preflight OPTIONS request a browser sends first, the Access-Control-Allow-* headers the office answers with, and why CORS protects browsers, not your API. cors() in apigw/demo.py answers a preflight from the school's own web site and from a stranger's.

🧒 Explain like I'm 5

A parent's browser 🌐 is a very careful helper. The parent is reading the school's web page, https://school.example. That page asks the browser: "please fetch Aishwarya's marks from https://api.school.example". That is another address.

So the browser first knocks on the office door and asks: "The page from school.example wants to send a GET. Is that all right?" That knock is the preflight (OPTIONS).

The clerk answers: "Yes — for school.example, these methods, these headers, and you may remember this answer for 10 minutes." Then the browser sends the real request.

A page from evil.example asks the same. The clerk says no. The browser then refuses to give that page the answer.

Notice: it is the browser that obeys. A person using curl never asks first — the clerk's "no" does not stop them.

🗺️ Diagram

sequenceDiagram
    participant P as 📄 page on school.example
    participant B as 🌐 browser
    participant O as 🛎️ front office
    P->>B: fetch api/students/7
    B->>O: OPTIONS /students/7 · Origin: https://school.example
    O-->>B: 204 · Allow-Origin: https://school.example · Max-Age: 600
    B->>O: GET /students/7 · Origin: https://school.example
    O-->>B: 200 · Access-Control-Allow-Origin: https://school.example
    B-->>P: the answer
    Note over B,O: Origin https://evil.example → 403, and the browser blocks the page

🗺️ Drawn version + a lab: https://school-edh.pages.dev/apigateway/lesson-diagrams.html#l09

❓ What

Origin — scheme + host + port of the page: https://school.example. http://school.example is a different origin.
Same-origin policy — a browser rule: a page may not read answers from another origin unless that origin allows it. CORS (Cross-Origin Resource Sharing) is the way to allow it.
Preflight — for "non-simple" requests (e.g. JSON bodies, an Authorization header, PUT/DELETE), the browser first sends OPTIONS with Origin, Access-Control-Request-Method and Access-Control-Request-Headers.
The answer headers — Access-Control-Allow-Origin (one origin, or *), Access-Control-Allow-Methods, Access-Control-Allow-Headers, Access-Control-Max-Age (how long the browser may remember the answer), and Access-Control-Allow-Credentials (cookies; then the origin may not be *).
The real response needs a header too — Access-Control-Allow-Origin must also be on the actual GET/POST answer, including error answers, or the page cannot read it.
In API Gateway — HTTP APIs: one corsConfiguration, and the office answers preflights itself. REST APIs: an OPTIONS method (usually a mock integration) returns the headers; with a proxy integration your back end must add Access-Control-Allow-Origin to its own responses; add the headers to gateway responses (DEFAULT_4XX, DEFAULT_5XX) so browser pages can read errors.

🤔 Why

Because almost every web app calls an API on another origin, and a missing header is the most common "it works in curl but not in the browser" bug. And because many people think CORS is a security wall for the API. It is not: it protects the user's browser from pages that try to read data with the user's cookies. Your API still needs auth (lesson 06).

🔧 How (in this repo)

Gateway._handle() in apigw/gateway.py answers every OPTIONS itself, before route matching (like an HTTP API's CORS setting): an origin in cors_origins gets 204 with the four Access-Control-* headers; any other origin gets 403 CORS origin not allowed. Gateway.handle() also adds Access-Control-Allow-Origin to the real answer when the request's Origin is allowed. office() allows exactly one origin: https://school.example.

🧪 Try it

python3 apigw/demo.py cors
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office
gw, _ = office()
for origin in ("https://school.example", "http://school.example", "https://school.example.evil.com"):
    st, hd, _ = gw.handle("OPTIONS", "/marks", {"Origin": origin, "Access-Control-Request-Method": "POST"})
    print(st, origin, hd.get("Access-Control-Allow-Origin"))
st, hd, out = gw.handle("GET", "/students/9", {"Origin": "https://evil.example"})
print("GET from evil.example:", st, out, "· Allow-Origin header:", hd.get("Access-Control-Allow-Origin"))
EOF

Be the browser yourself, on the live office:

python3 apigw/demo.py serve &
sleep 1                                # give the office a second to open
curl -i -X OPTIONS -H "Origin: https://school.example" -H "Access-Control-Request-Method: GET" localhost:8080/students/7
curl -i -X OPTIONS -H "Origin: https://evil.example" localhost:8080/students/7
curl -i -H "Origin: https://evil.example" localhost:8080/students/9
kill %1

✅ Verify — what you should see

cors prints OPTIONS /students/7 → 204 Access-Control-Allow-Origin: https://school.example Access-Control-Allow-Methods: GET,POST,PUT,DELETE Access-Control-Allow-Headers: authorization,content-type,x-api-key Access-Control-Max-Age: 600, then OPTIONS /students/7 → 403 {'message': 'CORS origin not allowed'} for https://evil.example, then the real GET with X-Cache: Miss Access-Control-Allow-Origin: https://school.example.

Your snippet prints 204 https://school.example https://school.example, 403 http://school.example None (a different scheme is a different origin) and 403 https://school.example.evil.com None (a look-alike name is not the same origin). The last line is the important one: GET from evil.example: 200 {'id': '9', 'name': 'Katrina', 'class': '9A'} · Allow-Origin header: None — the office did answer; only a browser would hide the answer from the page.

On the live office: HTTP/1.0 204 No Content with the four Access-Control-* headers; HTTP/1.0 403 Forbidden with {"message": "CORS origin not allowed"}; and for the plain GET from evil.example, HTTP/1.0 200 OK with the data and no Access-Control-Allow-Origin header.

🏁 What you just proved

You can read a preflight like a browser does, and you saw with your own eyes that CORS does not stop curl — it is a rule browsers follow, not a lock on the API.

⚠️ Common mistakes

Access-Control-Allow-Origin: * together with credentials (cookies) — browsers reject it
CORS headers on the OPTIONS answer but not on the real response (or not on 4XX/5XX errors)
matching origins with "ends with school.example" — evil-school.example passes; list exact origins
"fixing" a real auth problem by widening CORS — CORS is not auth
forgetting authorization in Allow-Headers, so every request with a token fails its preflight

🏭 In production

On a real account — CORS on an HTTP API is one setting:

aws apigatewayv2 update-api --api-id a1b2c3 --cors-configuration \
    AllowOrigins=https://school.example,AllowMethods=GET,POST,AllowHeaders=authorization,content-type,MaxAge=600

On a REST API, let browser pages read the office's own errors too:

cat > cors-4xx.json <<'EOF'
{ "gatewayresponse.header.Access-Control-Allow-Origin": "'https://school.example'" }
EOF
aws apigateway put-gateway-response --rest-api-id abc123 --response-type DEFAULT_4XX \
    --response-parameters file://cors-4xx.json

(The inner single quotes are required: they mark a fixed value, not a variable.)

And a Lambda proxy back end adds the header to its own answers:

return {"statusCode": 200,
        "headers": {"Access-Control-Allow-Origin": "https://school.example"},
        "body": json.dumps(student)}

🏭 Why this matters in production: list exact origins per stage (the dev web site and the prod web site are different), include the headers on errors, and never treat CORS as a replacement for an authorizer.

⏭️ Next

Browsers are happy. But the address is still abc123.execute-api.ap-south-1.amazonaws.com. Give the office a name plate — custom domains and TLS.

git checkout lesson-10-custom-domains

← Previouscaching Next →custom domains

This page is the lesson's README from the lesson-09-cors branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.