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

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

🎫 धडा 05 — OAuth 2 आणि OIDC: शाळेच्या account ने log in करा

📍 तुम्ही इथे आहात: 16 पैकी धडा 05 · मागे: lesson-04-authentication · पुढे: lesson-06-authorization

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

धडे 01–04, आणि delegated login. शाळेचे app passwords ठेवत नाही. ते user ला शाळेच्या identity provider कडे पाठवते, आणि परत एक ID token (OpenID Connect) आणि एक access token (OAuth 2) मिळवते. तुम्ही token योग्य पद्धतीने तपासता — algorithm, signature, issuer, audience, expiry — आणि प्रत्येक खोटेपणा fail होताना पाहता. मग PKCE, ज्यामुळे चोरलेला authorization code निरुपयोगी होतो. sec/demo.py मधले oauth() हे दाखवते.

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

Library ला दीपिका कोण आहे ते जाणून घ्यायचे आहे. ती तिचा गुप्त शब्द विचारत नाही — तो फक्त शाळेची ओळखपत्र खिडकी ऐकू शकते.

म्हणून library दीपिकाला ओळखपत्र खिडकीकडे पाठवते. ती जाण्याआधी library एका कागदावर एक गुप्त शब्द लिहिते, तो खिशात ठेवते, आणि दीपिकाला खिडकीवर दाखवण्यासाठी फक्त त्या शब्दाचा ठसा देते (PKCE challenge).

ओळखपत्र खिडकी दीपिकाला तपासते आणि तिला एक पावती देते (authorization code). ती ती library कडे परत आणते. Library ती पावती ओळखपत्र खिडकीकडे घेऊन जाते आणि खिशातला गुप्त शब्द दाखवते (verifier). खिडकी तपासते: "या शब्दापासून तो ठसा बनतो का?" हो → खिडकी दीपिकाचे ओळखपत्र (tokens) देते.

वाटेत एखाद्या अनोळखी माणसाने पावती चोरली तरी ती निरुपयोगी असते — library च्या खिशातला शब्द त्याच्याकडे नसतो.

आणि library ओळखपत्रावर विश्वास ठेवण्याआधी ते तपासते: शाळेचा शिक्का (signature), शाळेच्या ओळखपत्र खिडकीकडून (issuer), canteen साठी नाही तर library साठी (audience), आणि expired नाही.

🗺️ आकृती

sequenceDiagram
    participant U as 🧒 Dipika's browser
    participant A as 📚 school app
    participant I as 🎫 identity provider
    A->>A: verifier = random · challenge = BASE64URL(SHA256(verifier))
    A->>U: redirect to /authorize with response_type=code, code_challenge (S256), state, nonce
    U->>I: log in (password + MFA or passkey)
    I->>U: redirect back with code and state
    U->>A: code + state
    A->>I: POST /token: code + code_verifier
    I->>I: SHA256(verifier) == challenge?
    I->>A: ID token + access token
    A->>A: check alg · signature · iss · aud · exp · nonce

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

❓ काय

OAuth 2.0 — app ला user चा password न पाहता, user च्या वतीने API call करण्यासाठी access token मिळवण्याची पद्धत. हे access बद्दल आहे.
OpenID Connect (OIDC) — OAuth 2.0 वरचा एक थर जो ID token जोडतो: कोणी login केले ते सांगणारा signed JWT. हे login बद्दल आहे.
Authorization code flow — browser ला फक्त अल्पायुषी code मिळतो; app तो back-channel call मध्ये tokens साठी बदलून घेते. हाच flow वापरायचा.
PKCE (RFC 7636) — "Proof Key for Code Exchange". App एक random code verifier (43–128 अक्षरे) बनवते, code_challenge_method=S256 सह code_challenge = BASE64URL(SHA256(verifier)) पाठवते, आणि नंतर verifier आपल्याकडे आहे हे सिद्ध करते. फक्त चोरलेला code वापरता येत नाही. हे प्रत्येक client साठी वापरा — browser apps आणि phone apps साठी आवश्यक, आणि server apps साठीही शिफारस केलेले.
Implicit flow नाही — tokens थेट URL मध्ये टाकणारा जुना flow. OAuth 2.0 Security Best Current Practice (RFC 9700) तो वापरू नका असे सांगते. त्याऐवजी code + PKCE वापरा.
state आणि nonce — state उत्तराला app ने सुरू केलेल्या request शी जोडतो (तो login callback वरचा CSRF थांबवतो). nonce ID token मध्ये जातो; app तो जुळतो का ते तपासते, म्हणजे जुना ID token पुन्हा वापरता (replay) येत नाही.
ID token तपासणे — कोणत्याही claim वर विश्वास ठेवण्याआधी:
- algorithm — फक्त तुम्हाला अपेक्षित असलेला (IdP कडून RS256 / ES256); none नाकारा,
- signature — IdP ने प्रकाशित केलेल्या keys (JWKS) ने,
- iss — तुमचा विश्वास असलेला अचूक issuer,
- aud — तुमचाच client id (दुसऱ्या app साठीचा token तुमच्यासाठी नाही),
- exp — expired नाही (फक्त थोडा clock skew चालू द्या),
- nonce — तुम्ही पाठवलेली value.
JWT signed असतो, encrypted नाही — कोणीही त्याचे claims वाचू शकतो (base64url). Signature फक्त कोणी ते बदलले नाहीत हे सिद्ध करते. JWT मध्ये कधीही secrets ठेवू नका.

🤔 का

कारण तुम्ही सोडलेली प्रत्येक token तपासणी म्हणजे एक दार. Signature सोडले तर कोणीही "role": "admin" लिहू शकतो. aud सोडले तर canteen app ला दिलेला token library मध्ये चालतो. exp सोडले तर गेल्या वर्षी चोरलेला token अजूनही चालतो. alg: none स्वीकारले तर signature तपासणी हल्लेखोरच बंद करतो. आणि PKCE शिवाय, त्याच phone वरच्या दुष्ट app ने पकडलेला, किंवा log मध्ये leak झालेला code, user च्या tokens मध्ये बदलतो.

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

sec/identity.py मध्ये: make_jwt(claims, secret, alg) header.payload.signature token बनवते (HMAC-SHA256 — shared secret मुळे lab छोटा राहतो; खरे IdPs private key ने sign करतात आणि public keys प्रकाशित करतात). verify_jwt(token, secret, issuer, audience, now) या क्रमाने तपासते: algorithm HS256 च असला पाहिजे, signature, iss, aud, मग exp. pkce_pair(verifier) S256 challenge परत देते; pkce_ok(challenge, verifier) तो पुन्हा गणन करते. Lab मध्ये nonce चे model नाही — प्रत्यक्ष वापरात पाहा.

🧪 करून पाहा

python3 sec/demo.py oauth
python3 - <<'EOF'
import sys, base64, json; sys.path.insert(0, "sec"); from identity import make_jwt, verify_jwt, pkce_pair, pkce_ok
NOW, KEY, ISS = 1_790_000_000, "school-idp-secret", "https://login.school.example"
tok = make_jwt(dict(iss=ISS, aud="school-app", sub="dipika", role="parent", exp=NOW + 300), KEY)
h, p, s = tok.split(".")
claims = json.loads(base64.urlsafe_b64decode(p + "=" * (-len(p) % 4)))
print("anyone can READ the claims:", claims)
claims["role"] = "admin"
p2 = base64.urlsafe_b64encode(json.dumps(claims).encode()).rstrip(b"=").decode()
print("role changed to admin →", verify_jwt(f"{h}.{p2}.{s}", KEY, ISS, "school-app", NOW)[1])
other = make_jwt(dict(iss="https://login.other.example", aud="school-app", exp=NOW + 300), KEY)
print("another issuer        →", verify_jwt(other, KEY, ISS, "school-app", NOW)[1])
print("five minutes later    →", verify_jwt(tok, KEY, ISS, "school-app", NOW + 300)[1])
v, c = pkce_pair("dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk")
print("challenge (S256)      →", c)
print("same as RFC 7636, Appendix B →", c == "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM")
print("right verifier →", pkce_ok(c, v), "· sending the challenge back →", pkce_ok(c, c))
EOF

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

oauth हे print करते:

── the ID token the school login gives the app (OIDC) — checked before trusting any claim:
   good       → ok
   forged     → bad signature
   alg none   → algorithm 'none' refused
   other app  → wrong audience
   expired    → expired
── PKCE: the app sends challenge E9Melhoa2OwvFrEM… · later proves it with the verifier → True · a thief with only the code → False
   authorization code + PKCE for browsers and phones · never the implicit flow · tokens short-lived

तुमचा snippet हे print करतो:

anyone can READ the claims: {'iss': 'https://login.school.example', 'aud': 'school-app', 'sub': 'dipika', 'role': 'parent', 'exp': 1790000300}
role changed to admin → bad signature
another issuer        → wrong issuer
five minutes later    → expired
challenge (S256)      → E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
same as RFC 7636, Appendix B → True
right verifier → True · sending the challenge back → False

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

JWT मधले claims कोणीही वाचू शकतो — फक्त signature त्यांचे रक्षण करते, आणि एक बदललेला claim ते मोडतो. प्रत्येक तपासणी वेगळा खोटेपणा नाकारते: alg none, दुसऱ्या app चा token, दुसऱ्या issuer चा token, जुना token. Lab चा PKCE challenge RFC 7636 मधल्या उदाहरणाशी अगदी जुळतो. आणि challenge उघडपणे प्रवास करतो; फक्त verifier च code वापरू शकतो.

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

JWT decode करून तो verify न करता claims वापरणे (verify_signature=False)
token च्या header ला algorithm निवडू देणे — यादी निश्चित करा (algorithms=["RS256"])
aud सोडणे, त्यामुळे त्याच IdP चा कोणताही token स्वीकारला जातो
नव्या app मध्ये implicit flow, किंवा "password grant"
state / nonce नाही, किंवा IdP सैलपणे जुळवतो असा redirect_uri
दिवसभर टिकणारे access tokens, XSS वाचू शकेल अशा localStorage मध्ये ठेवलेले
login चा पुरावा म्हणून access token वापरणे — ते ID token चे काम आहे

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

खऱ्या account वर — authorization code flow आणि PKCE सह OIDC client (Python, Authlib + Flask). तो IdP चे discovery document वाचतो, state आणि nonce पाठवतो, आणि ID token तपासतो:

from authlib.integrations.flask_client import OAuth
oauth = OAuth(app)
oauth.register(
    name="school",
    server_metadata_url="https://login.school.example/.well-known/openid-configuration",
    client_id=os.environ["OIDC_CLIENT_ID"], client_secret=os.environ["OIDC_CLIENT_SECRET"],
    client_kwargs={"scope": "openid email profile", "code_challenge_method": "S256"},
)
@app.route("/login")
def login():
    return oauth.school.authorize_redirect(url_for("callback", _external=True))
@app.route("/callback")
def callback():
    token = oauth.school.authorize_access_token()     # checks state, swaps code + verifier, validates the ID token and nonce
    session.clear(); session["user"] = token["userinfo"]["sub"]
    return redirect("/")

Token स्वतः verify करणे (access tokens घेणारी API), PyJWT आणि IdP च्या JWKS सह:

import jwt
jwks = jwt.PyJWKClient("https://login.school.example/.well-known/jwks.json")
key = jwks.get_signing_key_from_jwt(token).key
claims = jwt.decode(token, key, algorithms=["RS256"],               # pinned — never from the header
                    audience="school-api", issuer="https://login.school.example",
                    leeway=30, options={"require": ["exp", "iss", "aud", "sub"]})

Browser app (single-page app) मध्ये oidc-client-ts सारखी certified library वापरा, response_type: "code" सह — PKCE default ने चालू असते — आणि tokens अल्पायुषी ठेवा.

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: managed identity provider (Amazon Cognito, Microsoft Entra ID, Okta, Auth0, Keycloak) आणि certified client library वापरा. अचूक redirect URIs register करा. Access tokens लहान (minutes) ठेवा, refresh-token rotation वापरा, आणि या धड्यातली प्रत्येक तपासणी library ला करू द्या — मग दुसऱ्या audience साठीचा token नाकारला जातो का ते test करा.

⏭️ पुढे

Token सांगतो दीपिका कोण आहे. ती कोणते records उघडू शकते ते तो सांगत नाही. पुढे: बहुतेक APIs विसरतात ती authorization तपासणी.

git checkout lesson-06-authorization

🎫 Lesson 05 — OAuth 2 and OIDC: log in with the school account

📍 You are here: Lesson 05 of 16 · Previous: lesson-04-authentication · Next: lesson-06-authorization

📦 What's in this branch

Lessons 01–04, plus delegated login. The school app does not keep passwords. It sends the user to the school's identity provider, and gets back an ID token (OpenID Connect) and an access token (OAuth 2). You check a token the right way — algorithm, signature, issuer, audience, expiry — and see each forgery fail. Then PKCE, which makes a stolen authorization code useless. oauth() in sec/demo.py shows it.

🧒 Explain like I'm 5

The library wants to know who Dipika is. It does not ask for her secret word — only the school's ID desk may hear that.

So the library sends Dipika to the ID desk. Before she goes, the library writes a secret word on a piece of paper, keeps it in its pocket, and gives Dipika only a fingerprint of that word to show the desk (the PKCE challenge).

The ID desk checks Dipika and gives her a claim ticket (the authorization code). She brings it back to the library. The library takes the ticket to the ID desk and shows the secret word from its pocket (the verifier). The desk checks: "does this word make that fingerprint?" Yes → the desk hands over Dipika's ID card (the tokens).

If a stranger steals the claim ticket on the way, it is useless — he does not have the word in the library's pocket.

And the library checks the ID card before it trusts it: stamped by the school (signature), from the school's ID desk (issuer), for the library and not the canteen (audience), and not expired.

🗺️ Diagram

sequenceDiagram
    participant U as 🧒 Dipika's browser
    participant A as 📚 school app
    participant I as 🎫 identity provider
    A->>A: verifier = random · challenge = BASE64URL(SHA256(verifier))
    A->>U: redirect to /authorize with response_type=code, code_challenge (S256), state, nonce
    U->>I: log in (password + MFA or passkey)
    I->>U: redirect back with code and state
    U->>A: code + state
    A->>I: POST /token: code + code_verifier
    I->>I: SHA256(verifier) == challenge?
    I->>A: ID token + access token
    A->>A: check alg · signature · iss · aud · exp · nonce

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

❓ What

OAuth 2.0 — a way for an app to get an access token to call an API on a user's behalf, without seeing the user's password. It is about access.
OpenID Connect (OIDC) — a layer on top of OAuth 2.0 that adds an ID token: a signed JWT that says who logged in. It is about login.
Authorization code flow — the browser gets only a short-lived code; the app swaps it for tokens in a back-channel call. This is the flow to use.
PKCE (RFC 7636) — "Proof Key for Code Exchange". The app makes a random code verifier (43–128 characters), sends code_challenge = BASE64URL(SHA256(verifier)) with code_challenge_method=S256, and later proves it holds the verifier. A stolen code alone cannot be redeemed. Use it for every client — required for browser apps and phone apps, and recommended for server apps too.
No implicit flow — the old flow that put tokens straight into the URL. The OAuth 2.0 Security Best Current Practice (RFC 9700) says not to use it. Use code + PKCE instead.
state and nonce — state ties the answer to the request the app started (it stops CSRF on the login callback). nonce goes into the ID token; the app checks it matches, so an old ID token cannot be replayed.
Checking an ID token — before trusting any claim:
- algorithm — only the one you expect (RS256 / ES256 from an IdP); refuse none,
- signature — with the IdP's published keys (the JWKS),
- iss — the exact issuer you trust,
- aud — your own client id (a token for another app is not for you),
- exp — not expired (allow only a small clock skew),
- nonce — the value you sent.
A JWT is signed, not encrypted — anyone can read its claims (base64url). The signature only proves nobody changed them. Never put secrets in a JWT.

🤔 Why

Because every token check you skip is a door. Skip the signature and anyone can write "role": "admin". Skip aud and a token issued to the canteen app works at the library. Skip exp and a token stolen last year still works. Accept alg: none and the signature check is switched off by the attacker. And without PKCE, a code caught by a malicious app on the same phone, or leaked in a log, turns into the user's tokens.

🔧 How (in this repo)

In sec/identity.py: make_jwt(claims, secret, alg) builds a header.payload.signature token (HMAC-SHA256 — a shared secret keeps the lab small; real IdPs sign with a private key and publish the public keys). verify_jwt(token, secret, issuer, audience, now) checks, in order: the algorithm must be HS256, the signature, iss, aud, then exp. pkce_pair(verifier) returns the S256 challenge; pkce_ok(challenge, verifier) recomputes it. nonce is not modelled in the lab — see In production.

🧪 Try it

python3 sec/demo.py oauth
python3 - <<'EOF'
import sys, base64, json; sys.path.insert(0, "sec"); from identity import make_jwt, verify_jwt, pkce_pair, pkce_ok
NOW, KEY, ISS = 1_790_000_000, "school-idp-secret", "https://login.school.example"
tok = make_jwt(dict(iss=ISS, aud="school-app", sub="dipika", role="parent", exp=NOW + 300), KEY)
h, p, s = tok.split(".")
claims = json.loads(base64.urlsafe_b64decode(p + "=" * (-len(p) % 4)))
print("anyone can READ the claims:", claims)
claims["role"] = "admin"
p2 = base64.urlsafe_b64encode(json.dumps(claims).encode()).rstrip(b"=").decode()
print("role changed to admin →", verify_jwt(f"{h}.{p2}.{s}", KEY, ISS, "school-app", NOW)[1])
other = make_jwt(dict(iss="https://login.other.example", aud="school-app", exp=NOW + 300), KEY)
print("another issuer        →", verify_jwt(other, KEY, ISS, "school-app", NOW)[1])
print("five minutes later    →", verify_jwt(tok, KEY, ISS, "school-app", NOW + 300)[1])
v, c = pkce_pair("dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk")
print("challenge (S256)      →", c)
print("same as RFC 7636, Appendix B →", c == "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM")
print("right verifier →", pkce_ok(c, v), "· sending the challenge back →", pkce_ok(c, c))
EOF

✅ Verify — what you should see

oauth prints:

── the ID token the school login gives the app (OIDC) — checked before trusting any claim:
   good       → ok
   forged     → bad signature
   alg none   → algorithm 'none' refused
   other app  → wrong audience
   expired    → expired
── PKCE: the app sends challenge E9Melhoa2OwvFrEM… · later proves it with the verifier → True · a thief with only the code → False
   authorization code + PKCE for browsers and phones · never the implicit flow · tokens short-lived

Your snippet prints:

anyone can READ the claims: {'iss': 'https://login.school.example', 'aud': 'school-app', 'sub': 'dipika', 'role': 'parent', 'exp': 1790000300}
role changed to admin → bad signature
another issuer        → wrong issuer
five minutes later    → expired
challenge (S256)      → E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
same as RFC 7636, Appendix B → True
right verifier → True · sending the challenge back → False

🏁 What you just proved

The claims inside a JWT are readable by anyone — only the signature protects them, and one changed claim breaks it. Each check refuses a different forgery: alg none, another app's token, another issuer's token, an old token. The lab's PKCE challenge matches the example in RFC 7636 exactly. And the challenge travels in the open; only the verifier redeems the code.

⚠️ Common mistakes

decoding a JWT and using the claims without verifying it (verify_signature=False)
letting the token's header choose the algorithm — pin the list (algorithms=["RS256"])
skipping aud, so any token from the same IdP is accepted
the implicit flow, or the "password grant", in a new app
no state / nonce, or a redirect_uri that the IdP matches loosely
access tokens that live for days, stored in localStorage where XSS can read them
using an access token as proof of login — that is the ID token's job

🏭 In production

On a real account — an OIDC client with the authorization code flow and PKCE (Python, Authlib + Flask). It reads the IdP's discovery document, sends state and nonce, and checks the ID token:

from authlib.integrations.flask_client import OAuth
oauth = OAuth(app)
oauth.register(
    name="school",
    server_metadata_url="https://login.school.example/.well-known/openid-configuration",
    client_id=os.environ["OIDC_CLIENT_ID"], client_secret=os.environ["OIDC_CLIENT_SECRET"],
    client_kwargs={"scope": "openid email profile", "code_challenge_method": "S256"},
)
@app.route("/login")
def login():
    return oauth.school.authorize_redirect(url_for("callback", _external=True))
@app.route("/callback")
def callback():
    token = oauth.school.authorize_access_token()     # checks state, swaps code + verifier, validates the ID token and nonce
    session.clear(); session["user"] = token["userinfo"]["sub"]
    return redirect("/")

Verifying a token yourself (an API that receives access tokens), with PyJWT and the IdP's JWKS:

import jwt
jwks = jwt.PyJWKClient("https://login.school.example/.well-known/jwks.json")
key = jwks.get_signing_key_from_jwt(token).key
claims = jwt.decode(token, key, algorithms=["RS256"],               # pinned — never from the header
                    audience="school-api", issuer="https://login.school.example",
                    leeway=30, options={"require": ["exp", "iss", "aud", "sub"]})

In a browser app (a single-page app), use a certified library such as oidc-client-ts, with response_type: "code" — PKCE is on by default — and keep tokens short-lived.

🏭 Why this matters in production: use a managed identity provider (Amazon Cognito, Microsoft Entra ID, Okta, Auth0, Keycloak) and a certified client library. Register exact redirect URIs. Keep access tokens short (minutes), use refresh-token rotation, and let the library do every check in this lesson — then test that a token for another audience is refused.

⏭️ Next

The token says who Dipika is. It does not say which records she may open. Next: the authorization check most APIs forget.

git checkout lesson-06-authorization

← Previousauthentication Next →authorization

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