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

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

🔐 धडा 06 — आत कोण येऊ शकतो: IAM, JWT आणि Lambda authorizers

📍 तुम्ही इथे आहात: 12 पैकी धडा 06 · मागे: lesson-05-stages-deployments · पुढे: lesson-07-throttling

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

धडे 01–05, आणि badge ची तपासणी: JWT authorizer (signature, issuer, audience, expiry, मग scope), Lambda authorizer (तुमचा स्वतःचा code निर्णय घेतो), AWS मधल्या callers साठी IAM (SigV4) — आणि API key म्हणजे authentication का नाही. इथे भाग 1: front office संपतो. apigw/demo.py मधले auth() पाच tokens आणि दोन badges वापरून पाहते.

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

Desk वर clerk badge 🪪 मागतो. चांगल्या badge मध्ये चार गोष्टी असतात ज्या clerk तपासतो:

शिक्का खरा आहे (पेनने काढलेला नाही) — signature;
तो आपल्याच badge office कडून आला आहे — issuer;
तो या शाळेसाठी बनवला आहे, शेजारच्या library साठी नाही — audience;
तारीख उलटून गेलेली नाही — expiry.

कोणतीही तपासणी अपयशी → "तुम्ही कोण?" (401). चारही पास, पण badge वर "marks वाचू शकतो" असे आहे आणि visitor ला marks लिहायचे आहेत → "मी तुम्हाला ओळखतो, पण नाही" (403).

काही दारांवर स्वतःचा नियम असलेला खास पहारेकरी 🧑‍✈️ असतो — "फक्त T ने सुरू होणारे staff badges". तो म्हणजे Lambda authorizer.

आणि partners दाखवतात तो visitor pass number? तो clerk ला फक्त कोणता partner भेटी मोजतो आहे ते सांगतो. तो number copy करणारा कोणीही तो वापरू शकतो. तो badge नाही.

🗺️ आकृती

flowchart LR
    req["🙋 GET /students/me<br/>Authorization: Bearer …"] --> s{"🔏 signature?"}
    s -->|"forged"| u["401 bad signature"]
    s --> i{"🏫 issuer?"}
    i -->|"other issuer"| u2["401 wrong issuer"]
    i --> a{"🎯 audience = school-api?"}
    a -->|"library-api"| u3["401 wrong audience"]
    a --> e{"⏰ expired?"}
    e -->|"yes"| u4["401 expired"]
    e --> sc{"📜 scope?"}
    sc -->|"needs marks:write"| f["403 Forbidden"]
    sc --> ok["✅ 200 — principal teacher-42"]

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

❓ काय

401 विरुद्ध 403 — 401 Unauthorized: तुम्ही कोण आहात ते office ला माहीत नाही (token नाही, वाईट token). 403 Forbidden: तुम्ही कोण ते त्याला माहीत आहे, आणि उत्तर नाही आहे.
IAM authorization (SigV4) — caller प्रत्येक request वर AWS credentials ने सही करतो; office signature आणि caller ची execute-api:Invoke साठीची IAM policy तपासते. AWS मधल्या callers साठी (services, roles) सर्वोत्तम. REST आणि HTTP APIs.
Cognito user pool authorizer (REST APIs) — office Amazon Cognito user pool ने दिलेला token तपासते.
JWT authorizer (HTTP APIs) — Cognito किंवा कोणत्याही OIDC issuer साठी. ते issuer च्या public keys (JWKS) आणते आणि signature, iss, aud (किंवा client_id), exp, आणि ऐच्छिक scopes तपासते. Code लिहायची गरज नाही.
Lambda authorizer — तुमच्या function ला token (TOKEN type) किंवा request चे भाग (REQUEST type) मिळतात आणि ते IAM policy (किंवा HTTP APIs वर साधे हो/नाही) परत देते. त्याचे उत्तर identity नुसार एका TTL साठी cache होते — default 300 seconds (0 ने caching बंद होते; जास्तीत जास्त 3600).
Resource policy (REST APIs) — API वरच असलेली policy: फक्त काही accounts, IP ranges किंवा VPC endpoints ना परवानगी (धडा 12).
API keys — usage plans साठी client ओळखतात (धडा 07). Key म्हणजे वाटून घेतलेली string: ती apps, logs आणि screenshots मधून बाहेर पडते. ती कोणता client ते सांगते, कोण ते नाही. कधीही एकमेव संरक्षण नाही.

🤔 का

कारण स्वतः tokens तपासणारा प्रत्येक back end म्हणजे expiry किंवा audience विसरण्याची आणखी एक जागा. दारावरचा authorizer ही तपासणी एकदाच, एकाच पद्धतीने, कोणताही kitchen code चालण्याआधी करतो — आणि तपासलेली identity (principal) आत पाठवतो, म्हणजे kitchen तिच्यावर विश्वास ठेवू शकते. Audience ची तपासणी सर्वात महत्त्वाची: ती नसेल तर library app साठी बनवलेला token शाळेचा API उघडेल.

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

apigw/gateway.py मधले check_jwt() चार तपासण्या क्रमाने करते आणि (claims, None) किंवा (None, reason) परत देते. Gateway._handle() कारणासह 401 परत देते, मग route.scope तपासते (POST /marks ला marks:write लागतो) आणि तो नसेल तर 403 परत देते; token चा sub request चा principal बनतो. route.auth == "lambda" साठी ते apigw/demo.py मधले teacher_badge() call करते, जे फक्त badge-T-42 स्वीकारते. Demo मधले token() teacher-42 साठी एका तासाचा योग्य token बनवते.

🧪 करून पाहा

python3 apigw/demo.py auth
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office, token, JWT
from gateway import make_jwt, check_jwt
gw, c = office()
now = c()
print(check_jwt("hello", **JWT, now=now))
print(check_jwt(make_jwt(dict(iss="https://evil.example", aud="school-api", exp=now + 60), JWT["secret"]), **JWT, now=now))
print(check_jwt(make_jwt(dict(iss=JWT["issuer"], aud=["library-api", "school-api"], sub="katrina", exp=now + 60), JWT["secret"]), **JWT, now=now))
print(check_jwt(make_jwt(dict(iss=JWT["issuer"], aud="school-api", exp=now + 60), "guessed-secret"), **JWT, now=now))
w = token(c, scope="marks:read marks:write")
print(gw.handle("POST", "/marks", {"Authorization": "Bearer " + w}, {"student": "9", "subject": "science", "mark": 88})[0::2])
print(gw.handle("GET", "/staffroom", {"Authorization": "badge-T-42"})[0::2], gw.logs[-1]["principal"])
EOF

चालू office वर, घड्याळावरून बनवलेल्या एका तासाच्या खऱ्या token सह:

python3 apigw/demo.py serve &
sleep 1                                # give the office a second to open
TOKEN=$(python3 -c "import sys,time; sys.path.insert(0,'apigw'); from demo import token; print(token(time.time))")
curl localhost:8080/students/me
curl -H "Authorization: Bearer $TOKEN" localhost:8080/students/me
curl -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
     -d '{"student":"7","subject":"maths","mark":91}' localhost:8080/marks
curl -H "Authorization: badge-T-42" localhost:8080/staffroom
kill %1

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

auth प्रत्येक token साठी एक, असे print करते: no token → 401 {'message': 'Unauthorized', 'why': 'no token'}, forged → 401 … 'bad signature', expired → 401 … 'expired', other app's token → 401 … 'wrong audience', good → 200 {'you': 'teacher-42'}; मग POST /marks → 403 {'message': 'Forbidden', 'why': 'needs scope marks:write'}; मग Lambda authorizer: badge-S-1 साठी GET /staffroom → 403 {'message': 'User is not authorized to access this resource'} आणि badge-T-42 साठी 200 {'you': 'teacher-42'}.

तुमचा snippet (None, 'not a JWT'), (None, 'wrong issuer'), कतरिनाच्या token चे claims (school-api असलेली aud list स्वीकारली जाते), अंदाजाने लावलेल्या secret साठी (None, 'bad signature'), दोन्ही scopes असलेल्या token साठी (201, {'saved': {'student': '9', 'subject': 'science', 'mark': 88}, 'table': 'marks-prod'}), आणि (200, {'you': 'teacher-42'}) teacher-42 print करतो.

चालू office {"message": "Unauthorized", "why": "no token"}, मग {"you": "teacher-42"}, मग {"message": "Forbidden", "why": "needs scope marks:write"} (default token मध्ये फक्त marks:read आहे), मग badge साठी {"you": "teacher-42"} असे उत्तर देते.

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

प्रत्येक 401 आणि प्रत्येक 403 चे कारण तुम्ही सांगू शकता: badge वर चार तपासण्या, मग scope ची तपासणी — आणि Lambda authorizer म्हणजे त्याच दारावरचा तुमचा स्वतःचा नियम.

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

API key हेच एकमेव संरक्षण — ती client ओळखते; call कोण करतोय ते सिद्ध करत नाही
audience तपासणी नसलेला JWT authorizer (किंवा company मधल्या प्रत्येक app चा audience)
प्रत्येक user साठी सारख्याच असलेल्या header वर cache होणारा Lambda authorizer — एका user चे "हो" इतरांसाठीही उत्तर ठरते
gateway मध्ये token तपासणे आणि kitchen मध्ये request body मधल्या user id वर विश्वास ठेवणे — तपासलेला principal वापरा
browser app साठी IAM auth — SigV4 ला browser मध्ये AWS credentials लागतात; JWT वापरा

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

On a real account — HTTP API वरचा JWT authorizer (Cognito किंवा कोणताही OIDC issuer) आणि scope लागणारा route:

aws apigatewayv2 create-authorizer --api-id a1b2c3 --name school-jwt \
    --authorizer-type JWT --identity-source '$request.header.Authorization' \
    --jwt-configuration Audience=school-api,Issuer=https://cognito-idp.ap-south-1.amazonaws.com/ap-south-1_AbCdEf123
aws apigatewayv2 update-route --api-id a1b2c3 --route-id r0ute1 \
    --authorization-type JWT --authorizer-id au7h01 --authorization-scopes marks:write

AWS SAM — पूर्ण HTTP API साठी तेच:

SchoolApi:
  Type: AWS::Serverless::HttpApi
  Properties:
    Auth:
      DefaultAuthorizer: SchoolJwt
      Authorizers:
        SchoolJwt:
          IdentitySource: $request.header.Authorization
          JwtConfiguration:
            issuer: https://login.school.example
            audience: [school-api]

300-second result cache असलेला REST API Lambda authorizer:

aws apigateway create-authorizer --rest-api-id abc123 --name staff-badge --type TOKEN \
    --identity-source method.request.header.Authorization \
    --authorizer-uri arn:aws:apigateway:ap-south-1:lambda:path/2015-03-31/functions/arn:aws:lambda:ap-south-1:111122223333:function:staff-badge/invocations \
    --authorizer-result-ttl-in-seconds 300

🏭 Production मध्ये हे का महत्त्वाचे: प्रत्येक route ला authorizer हवा, किंवा तो public का आहे याचे लिखित कारण. Reviews तीन गोष्टी तपासतात: audience, प्रत्येक route चे scopes, आणि कोणताही route फक्त API key वर अवलंबून नाही.

⏭️ पुढे

भाग 1 पूर्ण झाला: तुम्ही कोण आहात ते office ला माहीत आहे. भाग 2 ते खरोखर चालवतो, सुरुवात दारावरच्या गर्दीपासून — throttling आणि usage plans.

git checkout lesson-07-throttling

🔐 Lesson 06 — Who may come in: IAM, JWT and Lambda authorizers

📍 You are here: Lesson 06 of 12 · Previous: lesson-05-stages-deployments · Next: lesson-07-throttling

📦 What's in this branch

Lessons 01–05, plus the badge check: a JWT authorizer (signature, issuer, audience, expiry, then scope), a Lambda authorizer (your own code decides), IAM (SigV4) for callers inside AWS — and why an API key is not authentication. This ends Part 1: the front office. auth() in apigw/demo.py tries five tokens and two badges.

🧒 Explain like I'm 5

At the desk, the clerk asks for a badge 🪪. A good badge has four things the clerk checks:

the stamp is real (not drawn with a pen) — the signature;
it comes from our badge office — the issuer;
it was made for this school, not for the library next door — the audience;
the date has not passed — the expiry.

Any check fails → "Who are you?" (401). All four pass, but the badge says "may read marks" and the visitor wants to write marks → "I know you, but no" (403).

Some doors have a special guard 🧑‍✈️ with their own rule — "only staff badges starting with T". That is a Lambda authorizer.

And the visitor pass number that partners show? It only tells the clerk which partner is counting visits. Anyone who copies the number can use it. It is not a badge.

🗺️ Diagram

flowchart LR
    req["🙋 GET /students/me<br/>Authorization: Bearer …"] --> s{"🔏 signature?"}
    s -->|"forged"| u["401 bad signature"]
    s --> i{"🏫 issuer?"}
    i -->|"other issuer"| u2["401 wrong issuer"]
    i --> a{"🎯 audience = school-api?"}
    a -->|"library-api"| u3["401 wrong audience"]
    a --> e{"⏰ expired?"}
    e -->|"yes"| u4["401 expired"]
    e --> sc{"📜 scope?"}
    sc -->|"needs marks:write"| f["403 Forbidden"]
    sc --> ok["✅ 200 — principal teacher-42"]

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

❓ What

401 vs 403 — 401 Unauthorized: the office does not know who you are (no token, bad token). 403 Forbidden: it knows who you are, and the answer is no.
IAM authorization (SigV4) — the caller signs each request with AWS credentials; the office checks the signature and the caller's IAM policy for execute-api:Invoke. Best for callers inside AWS (services, roles). REST and HTTP APIs.
Cognito user pool authorizer (REST APIs) — the office checks a token issued by an Amazon Cognito user pool.
JWT authorizer (HTTP APIs) — for Cognito or any OIDC issuer. It fetches the issuer's public keys (JWKS) and checks the signature, iss, aud (or client_id), exp, and optional scopes. No code to write.
Lambda authorizer — your function receives the token (TOKEN type) or request parts (REQUEST type) and returns an IAM policy (or, on HTTP APIs, a simple yes/no). Its answer is cached by identity for a TTL — 300 seconds by default (0 turns caching off; up to 3600).
Resource policy (REST APIs) — a policy on the API itself: allow only some accounts, IP ranges or VPC endpoints (lesson 12).
API keys — identify a client for usage plans (lesson 07). A key is a shared string: it leaks in apps, logs and screenshots. It says which client, not who. Never the only protection.

🤔 Why

Because every back end that checks tokens itself is one more place to forget the expiry or the audience. An authorizer at the door makes the check once, the same way, before any kitchen code runs — and passes the verified identity (principal) inward, so the kitchen can trust it. The audience check matters most: without it, a token made for the library app would open the school API.

🔧 How (in this repo)

check_jwt() in apigw/gateway.py makes the four checks in order and returns (claims, None) or (None, reason). Gateway._handle() returns 401 with the reason, then checks route.scope (POST /marks needs marks:write) and returns 403 if it is missing; the token's sub becomes the request's principal. For route.auth == "lambda" it calls teacher_badge() from apigw/demo.py, which accepts only badge-T-42. token() in the demo makes a good one-hour token for teacher-42.

🧪 Try it

python3 apigw/demo.py auth
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office, token, JWT
from gateway import make_jwt, check_jwt
gw, c = office()
now = c()
print(check_jwt("hello", **JWT, now=now))
print(check_jwt(make_jwt(dict(iss="https://evil.example", aud="school-api", exp=now + 60), JWT["secret"]), **JWT, now=now))
print(check_jwt(make_jwt(dict(iss=JWT["issuer"], aud=["library-api", "school-api"], sub="katrina", exp=now + 60), JWT["secret"]), **JWT, now=now))
print(check_jwt(make_jwt(dict(iss=JWT["issuer"], aud="school-api", exp=now + 60), "guessed-secret"), **JWT, now=now))
w = token(c, scope="marks:read marks:write")
print(gw.handle("POST", "/marks", {"Authorization": "Bearer " + w}, {"student": "9", "subject": "science", "mark": 88})[0::2])
print(gw.handle("GET", "/staffroom", {"Authorization": "badge-T-42"})[0::2], gw.logs[-1]["principal"])
EOF

On the live office, with a real one-hour token made from the clock:

python3 apigw/demo.py serve &
sleep 1                                # give the office a second to open
TOKEN=$(python3 -c "import sys,time; sys.path.insert(0,'apigw'); from demo import token; print(token(time.time))")
curl localhost:8080/students/me
curl -H "Authorization: Bearer $TOKEN" localhost:8080/students/me
curl -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
     -d '{"student":"7","subject":"maths","mark":91}' localhost:8080/marks
curl -H "Authorization: badge-T-42" localhost:8080/staffroom
kill %1

✅ Verify — what you should see

auth prints, one per token: no token → 401 {'message': 'Unauthorized', 'why': 'no token'}, forged → 401 … 'bad signature', expired → 401 … 'expired', other app's token → 401 … 'wrong audience', good → 200 {'you': 'teacher-42'}; then POST /marks → 403 {'message': 'Forbidden', 'why': 'needs scope marks:write'}; then the Lambda authorizer: GET /staffroom → 403 {'message': 'User is not authorized to access this resource'} for badge-S-1 and 200 {'you': 'teacher-42'} for badge-T-42.

Your snippet prints (None, 'not a JWT'), (None, 'wrong issuer'), the claims for Katrina's token (an aud list that contains school-api is accepted), (None, 'bad signature') for the guessed secret, (201, {'saved': {'student': '9', 'subject': 'science', 'mark': 88}, 'table': 'marks-prod'}) for the token with both scopes, and (200, {'you': 'teacher-42'}) teacher-42.

The live office answers {"message": "Unauthorized", "why": "no token"}, then {"you": "teacher-42"}, then {"message": "Forbidden", "why": "needs scope marks:write"} (the default token only has marks:read), then {"you": "teacher-42"} for the badge.

🏁 What you just proved

You can name the reason for every 401 and every 403: four checks on the badge, then a scope check — and a Lambda authorizer is simply your own rule at the same door.

⚠️ Common mistakes

an API key as the only protection — it identifies a client; it does not prove who is calling
a JWT authorizer with no audience check (or the audience of every app in the company)
a Lambda authorizer cached on a header that is the same for every user — one user's "yes" answers for others
checking the token in the gateway and trusting a user id from the request body in the kitchen — use the verified principal
IAM auth for a browser app — SigV4 needs AWS credentials in the browser; use JWT

🏭 In production

On a real account — a JWT authorizer on an HTTP API (Cognito or any OIDC issuer) and a route that needs a scope:

aws apigatewayv2 create-authorizer --api-id a1b2c3 --name school-jwt \
    --authorizer-type JWT --identity-source '$request.header.Authorization' \
    --jwt-configuration Audience=school-api,Issuer=https://cognito-idp.ap-south-1.amazonaws.com/ap-south-1_AbCdEf123
aws apigatewayv2 update-route --api-id a1b2c3 --route-id r0ute1 \
    --authorization-type JWT --authorizer-id au7h01 --authorization-scopes marks:write

AWS SAM — the same for a whole HTTP API:

SchoolApi:
  Type: AWS::Serverless::HttpApi
  Properties:
    Auth:
      DefaultAuthorizer: SchoolJwt
      Authorizers:
        SchoolJwt:
          IdentitySource: $request.header.Authorization
          JwtConfiguration:
            issuer: https://login.school.example
            audience: [school-api]

A REST API Lambda authorizer with a 300-second result cache:

aws apigateway create-authorizer --rest-api-id abc123 --name staff-badge --type TOKEN \
    --identity-source method.request.header.Authorization \
    --authorizer-uri arn:aws:apigateway:ap-south-1:lambda:path/2015-03-31/functions/arn:aws:lambda:ap-south-1:111122223333:function:staff-badge/invocations \
    --authorizer-result-ttl-in-seconds 300

🏭 Why this matters in production: every route should have an authorizer or a written reason why it is public. Reviews check three things: the audience, the scopes per route, and that no route relies on an API key alone.

⏭️ Next

Part 1 is done: the office knows who you are. Part 2 runs it for real, starting with the crowd at the door — throttling and usage plans.

git checkout lesson-07-throttling

← Previousstages deployments Next →throttling

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