14 · 🪪 प्रत्येक authentication पद्धत — हॉल पास दाखवण्याचा प्रत्येक मार्ग

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

धडे 01–14. तेच grades सात authentication पद्धतींमागे, एकही dependency नाही:

api/auth_demo.py — Basic · API key · opaque Bearer token · JWT (HS256) · HMAC request signing · session cookie · एक OAuth 2.0 token endpoint (client_credentials, refresh_token; password नाकारलेला)
api/auth_client.py — तारेवरचा प्रत्येक header, expire झालेला token, बनावट JWT, छेडछाड केलेली signature, पुन्हा पाठवलेली (replay) request, DELETE नाकारलेला scoped token
api/auth-output.txt — निरोगी run काय छापतो
🗺️ संपूर्ण नकाशा: https://school-edh.pages.dev/api/lesson-diagrams.html#l14 — अकरा flows चे चित्र, मुख्य तक्ता, प्रत्येक OAuth grant type, 401 विरुद्ध 403, निर्णय-मार्गदर्शन, चुका

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

Authentication म्हणजे "कोण विचारत आहे?"; authorization म्हणजे "त्यांना काय करण्याची परवानगी आहे?". धडा 06 ने एकाच प्रकारचा हॉल पास वापरला — program ची key. पण काउंटरवर आपण कोण आहोत हे सिद्ध करण्याचे अनेक मार्ग आहेत: प्रत्येक दारावर आपले नाव आणि password सांगा (Basic); program ची key दाखवा (API key); एकदा log in करा आणि मनगटी पट्टा घाला (Bearer token); office ने सही केलेला मनगटी पट्टा घाला, म्हणजे कोणतेही दार फोन न करता तो तपासू शकेल (JWT); browser ला तुमच्यासाठी cookie वाहू द्या (session); मुख्य office कडून परवानगीची चिठ्ठी घ्या म्हणजे app तुमच्या password शिवाय तुमच्या वतीने काम करू शकेल (OAuth 2.0); "Google ने sign in करा" (OpenID Connect); प्रत्येक लिफाफा बंद करून त्यावर तारीख टाका (HMAC signing); किंवा दार उघडण्याआधीच गेटवर certificates दाखवा (mutual TLS).

🗺️ आकृती

flowchart TD
  Q{who is asking?}
  Q -->|a person in a browser| S[session cookie · or Bearer token]
  Q -->|a person with an existing account| O[OpenID Connect]
  Q -->|a third-party app acting for a person| A[OAuth 2.0 · authorization code + PKCE]
  Q -->|a program on its own| C[OAuth client_credentials · API key + HMAC · mTLS]
  Q -->|your own services| M[mutual TLS · or internal JWTs]
  S & O & A & C & M --> R[401 = who are you? · 403 = I know you, and no]

❓ काय

पद्धत	काय प्रवास करते	Server स्थिती ठेवतो?	कशासाठी उत्तम
Basic	user:password, base64, प्रत्येक request वर	नाही	scripts, अंतर्गत tools — फक्त HTTPS
API key	header मधली लांब random string	keys चा table	server-to-server, वापराचे मोजमाप
Bearer token (opaque)	/login कडून मिळालेला token	tokens चा table	स्वतःचे apps; तत्काळ revoke
JWT	header.payload.signature	नाही — stateless	एकच login तपासणाऱ्या अनेक services
Session cookie	एक session id (HttpOnly, SameSite, Secure)	sessions चा table	एका site वरचे browser apps
OAuth 2.0	code → access token (+ refresh)	authorization server	third-party प्रवेश, सोपवलेले scopes
OpenID Connect	एक ID token (JWT) + access token	identity provider	"…ने sign in करा"
HMAC signing	method, path, वेळ, body वरची signature	secrets चा table	webhooks, AWS-पद्धतीचे APIs
Mutual TLS	client + server certificates	एक CA	service-to-service, zero trust

OAuth grant types: लोकांसाठी authorization_code + PKCE, programs साठी client_credentials, sign in राहण्यासाठी refresh_token, keyboard नसलेल्या screens साठी device code; password आणि implicit OAuth 2.1 draft मध्ये काढून टाकले आहेत.

🤔 का

प्रत्येक पद्धत म्हणजे स्थिती कोण ठेवतो आणि तुम्ही किती लवकर revoke करू शकता यामधला सौदा. Stateful token table तत्काळ revoke करतो पण प्रत्येक वेळी lookup लागतो; सही केलेला JWT lookup शिवाय वाढतो पण expire होईपर्यंत जिवंत राहतो. Caller नुसार निवड — माणूस की program — यातच बहुतेक निर्णय होतो.

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

auth_demo.py मध्ये प्रत्येक पद्धतीसाठी एक function आहे, प्रत्येक (user, role) परत देते किंवा Deny(challenge, why) raise करते; guard Deny चे WWW-Authenticate challenge सह 401 मध्ये रूपांतर करतो, आणि विद्यार्थ्याने केलेल्या DELETE चे (किंवा ज्याचा scope फक्त grades:read आहे अशा token ने केलेल्या DELETE चे) 403 मध्ये. Token endpoint JSON नव्हे तर form घेतो, जसे RFC 6749 सांगतो, आणि password grant ला unsupported_grant_type उत्तर देतो.

🧪 करून पाहा

python3 api/auth_demo.py &
python3 api/auth_client.py
# then by hand — the OAuth token endpoint speaks forms:
curl -s -X POST http://127.0.0.1:8082/token -d 'grant_type=client_credentials&client_id=report-bot&client_secret=s3cr3t-bot'
curl -s -X POST http://127.0.0.1:8082/token -d 'grant_type=password&username=teacher&password=chalk'   # refused

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

नावे दिलेले सात विभाग. प्रत्येक गहाळ किंवा चुकीचे credential म्हणजे WWW-Authenticate challenge सह 401; विद्यार्थ्याचा DELETE आणि फक्त-वाचण्याच्या OAuth token चा DELETE 403 असतात; बदललेला JWT bad signature ने fail होतो; replay केलेली HMAC request तिच्या timestamp मुळे नाकारली जाते; grant_type=password ला unsupported_grant_type मिळते. पूर्ण मजकूर api/auth-output.txt मध्ये आहे.

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

तुम्ही फक्त standard library वापरून प्रत्येक सामान्य credential दिले आणि तपासले — खऱ्या JWT आणि खऱ्या OAuth token endpoint सह — आणि "तुम्ही कोण?" आणि "मी तुम्हाला ओळखतो, पण नाही" यातला फरक तारेवर पाहिला.

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

साध्या HTTP वरून Basic किंवा tokens; browser JavaScript किंवा URLs मध्ये API keys.
JWT payload मध्ये secrets (तो वाचता येतो); revoke करण्याचा मार्ग नसलेले दीर्घकाळ चालणारे JWTs.
alg: none स्वीकारणे; hmac.compare_digest ऐवजी == ने tokens तुलना करणे.
HttpOnly, Secure, SameSite नसलेल्या cookies; localStorage मध्ये tokens.
Implicit flow किंवा PKCE नसणे; Authorization header log करणे.

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: धडा 06 मध्ये चुकीची API key 403 उत्तर देते; काटेकोरपणे अनोळखी key म्हणजे 401, आणि Stripe व GitHub 401 उत्तर देतात. दोन्ही अर्थ प्रत्यक्षात वापरात आहेत. जे कधीच बदलत नाही: 401 सोबत challenge असतो, 403 ओळखीच्या caller चे नाव घेतो, आणि प्रत्येक credential ची expiry तुम्ही जाणूनबुजून ठरवलेली असते.

⏭️ पुढे

धडा 15 — प्रत्येक API प्रकार: या कोर्सने एक REST काउंटर बांधला; आणखी वीस आकार आहेत.

14 · 🪪 Every authentication method — every way to show a hall pass

📦 What's in this branch

Lessons 01–14. The same grades behind seven authentication schemes, zero dependencies:

api/auth_demo.py — Basic · API key · opaque Bearer token · JWT (HS256) · HMAC request signing · session cookie · an OAuth 2.0 token endpoint (client_credentials, refresh_token; password refused)
api/auth_client.py — every header on the wire, an expired token, a forged JWT, a tampered signature, a replayed request, a scoped token refused a DELETE
api/auth-output.txt — what a healthy run prints
🗺️ The full map: https://school-edh.pages.dev/api/lesson-diagrams.html#l14 — eleven flows drawn, the master table, every OAuth grant type, 401 vs 403, a decision guide, the mistakes

🧒 Explain like I'm 5

Authentication is "who is asking?"; authorization is "what may they do?". Lesson 06 used one kind of hall pass — a program's key. But there are many ways to prove who you are at the counter: say your name and password at every door (Basic); show a program's key (API key); log in once and wear a wristband (Bearer token); wear a wristband the office signed so any door can check it without a phone call (JWT); let the browser carry a cookie for you (session); get a permission slip from the head office so an app can act for you without your password (OAuth 2.0); "sign in with Google" (OpenID Connect); seal and date every envelope (HMAC signing); or show certificates at the gate before the door even opens (mutual TLS).

🗺️ Diagram

flowchart TD
  Q{who is asking?}
  Q -->|a person in a browser| S[session cookie · or Bearer token]
  Q -->|a person with an existing account| O[OpenID Connect]
  Q -->|a third-party app acting for a person| A[OAuth 2.0 · authorization code + PKCE]
  Q -->|a program on its own| C[OAuth client_credentials · API key + HMAC · mTLS]
  Q -->|your own services| M[mutual TLS · or internal JWTs]
  S & O & A & C & M --> R[401 = who are you? · 403 = I know you, and no]

❓ What

Method	What travels	Server keeps state?	Best for
Basic	user:password, base64, every request	no	scripts, internal tools — HTTPS only
API key	a long random string in a header	the key table	server-to-server, metering
Bearer token (opaque)	a token from /login	the token table	first-party apps; instant revoke
JWT	header.payload.signature	no — stateless	many services verifying one login
Session cookie	a session id (HttpOnly, SameSite, Secure)	the session table	browser apps on one site
OAuth 2.0	code → access token (+ refresh)	the authorization server	third-party access, delegated scopes
OpenID Connect	an ID token (JWT) + access token	the identity provider	"sign in with…"
HMAC signing	a signature over method, path, time, body	the secret table	webhooks, AWS-style APIs
Mutual TLS	client + server certificates	a CA	service-to-service, zero trust

OAuth grant types: authorization_code + PKCE for people, client_credentials for programs, refresh_token to stay signed in, device code for screens without a keyboard; password and implicit are removed in the OAuth 2.1 draft.

🤔 Why

Every method is a trade between who keeps the state and how fast you can revoke. A stateful token table revokes instantly but costs a lookup; a signed JWT scales without a lookup but lives until it expires. Picking by caller — person or program — decides most of it.

🔧 How (in this repo)

auth_demo.py has one function per scheme, each returning (user, role) or raising Deny(challenge, why); the guard turns a Deny into a 401 with a WWW-Authenticate challenge, and a DELETE by a student (or by a token whose scope is only grades:read) into a 403. The token endpoint takes a form, not JSON, as RFC 6749 requires, and answers unsupported_grant_type to the password grant.

🧪 Try it

python3 api/auth_demo.py &
python3 api/auth_client.py
# then by hand — the OAuth token endpoint speaks forms:
curl -s -X POST http://127.0.0.1:8082/token -d 'grant_type=client_credentials&client_id=report-bot&client_secret=s3cr3t-bot'
curl -s -X POST http://127.0.0.1:8082/token -d 'grant_type=password&username=teacher&password=chalk'   # refused

✅ Verify — what you should see

Seven labelled sections. Every missing or wrong credential is a 401 with a WWW-Authenticate challenge; the student's DELETE and the read-only OAuth token's DELETE are 403; the edited JWT fails with bad signature; the replayed HMAC request is refused for its timestamp; grant_type=password gets unsupported_grant_type. The full text is in api/auth-output.txt.

🏁 What you just proved

You issued and verified every common credential with nothing but the standard library — including a real JWT and a real OAuth token endpoint — and you saw the difference between "who are you?" and "I know you, and no" on the wire.

⚠️ Common mistakes

Basic or tokens over plain HTTP; API keys in browser JavaScript or URLs.
Secrets inside a JWT payload (it is readable); long-lived JWTs with no way to revoke.
Accepting alg: none; comparing tokens with == instead of hmac.compare_digest.
Cookies without HttpOnly, Secure, SameSite; tokens in localStorage.
The implicit flow or no PKCE; logging the Authorization header.

🏭 Why this matters in production: a wrong API key in lesson 06 answers 403; strictly an unknown key is a 401, and Stripe and GitHub answer 401. Both readings exist in the wild. What never varies: a 401 carries a challenge, a 403 names a known caller, and every credential has an expiry you decided on purpose.

⏭️ Next

Lesson 15 — every API type: this course built one REST counter; there are twenty other shapes.

← Previousrest methods Next →api types

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