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

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

🎩 धडा 05 — Roles आणि STS: कार्ड नाही, टोपी

📍 तुम्ही इथे आहात: 12 पैकी धडा 05 · मागे: lesson-04-how-aws-decides · पुढे: lesson-06-machine-identities

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

धडे 01–04, आणि त्यासोबत roles: password नसलेली आणि कायमची key नसलेली identity, ती कोण assume करू शकतो ते सांगणारी trust policy, तात्पुरती credentials देणारा STS, आणि एका session ला मर्यादित करणारी session policy. Files: trust-ci-deployer.json, ci-deploy.json, session-read-only.json.

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

शाळेतल्या काही कामांसोबत एक टोपी 🎩 येते: "परीक्षा पर्यवेक्षक" ची टोपी परीक्षेचा हॉल उघडते. ती टोपी कोणाच्याच मालकीची नसते. तुम्ही ती घालायला ओळखपत्र कार्यालयाकडे मागता; कार्यालय टोपीच्या लेबलवरची यादी तपासते ("ही फक्त CI robot घालू शकतो"), आणि तुम्ही त्या यादीत असाल तर तुम्हाला ती टोपी एका तासासाठी मिळते. मग ती आपोआप नाहीशी होते.

टोपी घातली असताना तुमच्याकडे टोपीच्या परवानग्या असतात — तुमच्या स्वतःच्या नाहीत. आणि कार्यालय तुम्हाला त्यावर एक sticker लावून टोपी देऊ शकते: "आज फक्त बघा, हात लावू नका". तो sticker फक्त परवानग्या काढून घेऊ शकतो, कधीच नवीन देऊ शकत नाही.

हाच role: टोपी. लेबल म्हणजे तिची trust policy. एका तासाचा pass STS (Security Token Service) कडून येतो. Sticker म्हणजे session policy.

🗺️ आकृती

flowchart LR
    who["🤖 user/ci-robot"]
    trust["🏷️ trust policy<br/>Principal: user/ci-robot<br/>Action: sts:AssumeRole"]
    sts["🎟️ STS AssumeRole<br/>ASIA… key + session token<br/>expires in 1 hour"]
    sess["🎩 assumed-role/ci-deployer/build-42"]
    perm["📝 ci-deploy policy<br/>ecr:PutImage …"]
    who -->|"1 may I wear it?"| trust -->|"2 yes"| sts --> sess
    sess -->|"3 acts with"| perm

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

❓ काय

Role — दोन policies असलेली IAM identity: trust policy (role वरची resource policy: तो कोण assume करू शकतो, Principal सह) आणि permission policies (role काय करू शकतो). Password नाही, दीर्घकाळाची access key नाही.
STS — AssumeRole एक AccessKeyId (ASIA ने सुरू होणारी), एक SecretAccessKey, एक SessionToken आणि एक Expiration परत देतो. मूळ कालावधी 1 तास; तुम्ही 15 मिनिटांपासून role च्या कमाल session कालावधीपर्यंत (12 तासांपर्यंत) मागू शकता. Role chaining (एका role ने दुसरा role assume करणे) 1 तासापर्यंतच मर्यादित असते.
Session ARN — arn:aws:sts::111122223333:assumed-role/ci-deployer/build-42: role चे नाव आणि तुम्ही निवडलेले session चे नाव — CloudTrail हेच नोंदवतो, म्हणून अर्थपूर्ण नावे निवडा.
Session policy — AssumeRole सोबत दिली जाते (--policy किंवा --policy-arns). Effective permissions = role policies ∩ session policy. ती फक्त मर्यादित करू शकते.
दोन्ही बाजूंनी हो म्हणायला हवे — trust policy ने caller ला allow करायला हवे, आणि (accounts ओलांडताना, धडा 09) caller च्या स्वतःच्या policies नी त्या role वर sts:AssumeRole allow करायला हवे.

🤔 का

दीर्घकाळाच्या keys फुटतात — git मध्ये, logs मध्ये, laptops मध्ये — आणि कोणाच्या लक्षात येईपर्यंत चालूच राहतात. तात्पुरती credentials आपोआप संपतात, नाव असलेल्या session शी जोडलेली असतात, आणि त्यांना कधीच rotate करावे लागत नाही. AWS services, CI systems, इतर accounts आणि लोक (धडा 10) यांना access roles मधूनच मिळायला हवा.

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

iam/demo.py मधला roles() ci-robot आणि dipika साठी matches() ने trust statement तपासतो, तात्पुरत्या credentials चे एक उदाहरण print करतो, आणि मग session साठी decide() call करतो — एकदा फक्त role policy सह, आणि एकदा read-only session policy जोडून (session=).

🧪 करून पाहा

python3 iam/demo.py roles
python3 - <<'EOF'
import sys; sys.path.insert(0, "iam"); from evaluate import decide, load, matches
trust = load("trust-ci-deployer")["Statement"][0]
role = "arn:aws:iam::111122223333:role/ci-deployer"
print("ci-robot may assume:", matches(trust, "sts:AssumeRole", role, {}, "arn:aws:iam::111122223333:user/ci-robot"))
print("partner may assume: ", matches(trust, "sts:AssumeRole", role, {}, "arn:aws:iam::444455556666:user/ci-robot"))
sess = "arn:aws:sts::111122223333:assumed-role/ci-deployer/build-43"
ci = [("ci-deploy", load("ci-deploy"))]
wide = [("session-s3", {"Version": "2012-10-17", "Statement": [{"Effect": "Allow", "Action": "s3:*", "Resource": "*"}]})]
print("in both:            ", decide(sess, "ecr:GetAuthorizationToken", "*", identity=ci, session=[("session-read-only", load("session-read-only"))])[0])
print("session only:       ", decide(sess, "s3:GetObject", "arn:aws:s3:::school-reports/term1.pdf", identity=ci, session=wide)[0])
EOF

खऱ्या account वर (AWS CLI आणि credentials लागतात):

aws iam create-role --role-name ci-deployer --assume-role-policy-document file://iam/policies/trust-ci-deployer.json
aws iam put-role-policy --role-name ci-deployer --policy-name ci-deploy --policy-document file://iam/policies/ci-deploy.json
aws sts assume-role --role-arn arn:aws:iam::111122223333:role/ci-deployer --role-session-name build-42 --duration-seconds 3600
aws sts assume-role --role-arn arn:aws:iam::111122223333:role/ci-deployer --role-session-name build-43 --policy file://iam/policies/session-read-only.json

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

roles हे print करतो: 🎩 ci-robot … trust policy lets them ✅, 🎩 dipika … refuses 🚫, उदाहरणादाखल credentials ची ओळ, मग ✅ role session → ecr:PutImage ALLOW आणि 🚫 same session + read-only session policy IMPLICIT DENY — outside the session policy passed to AssumeRole. तुमचा snippet True, False (तेच user नाव, पण वेगळे account — लेबलवरचा principal नाही), ALLOW (दोघांनीही allow केलेले) आणि IMPLICIT DENY (session policy s3:* ला allow करते, पण role कडे ते कधीच नव्हते — session policy काही जोडू शकत नाही) print करतो. खऱ्या account वर assume-role एक Credentials block परत देतो, ज्याचा AccessKeyId ASIA ने सुरू होतो.

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

Role घातला जातो, तो कोणाच्या मालकीचा नसतो: trust policy तो कोण घालू शकतो ते निवडते, STS pass तात्पुरता बनवतो, आणि session policy role कडे आधीच असलेले फक्त कमीच करू शकते.

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

trust policy मध्ये "Principal": {"AWS": "*"} — कोणत्याही account मधला कोणीही प्रयत्न करू शकतो
trust policy (कोण) आणि permission policy (काय) यांची गल्लत करणे
"सुरक्षित राहावे म्हणून" 12 तासांचे sessions मागणे — जेवढे लहान तेवढे सुरक्षित
session1 सारखी session नावे — मग CloudTrail builds किंवा लोक वेगळे ओळखू शकत नाही

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: नीट चालवलेल्या AWS व्यवस्थांमध्ये जवळजवळ प्रत्येक caller हा role session असतो — services, pipelines, इतर accounts आणि SSO मधून येणारे लोक — आणि दीर्घकाळाच्या access keys ची संख्या जवळजवळ शून्य असते.

⏭️ पुढे

जो robot AWS मध्ये मुळीच नाही — GitHub Actions, एखादा pod, एखादा Lambda — त्याला साठवलेल्या key शिवाय टोपी कशी मिळते? Machine identities.

git checkout lesson-06-machine-identities

🎩 Lesson 05 — Roles & STS: the hat, not the card

📍 You are here: Lesson 05 of 12 · Previous: lesson-04-how-aws-decides · Next: lesson-06-machine-identities

📦 What's in this branch

Lessons 01–04, plus roles: an identity with no password and no permanent key, a trust policy that says who may assume it, STS issuing temporary credentials, and a session policy that narrows one session. Files: trust-ci-deployer.json, ci-deploy.json, session-read-only.json.

🧒 Explain like I'm 5

Some jobs in school come with a hat 🎩: the "exam invigilator" hat opens the exam hall. Nobody owns the hat. You ask the ID office to wear it; the office checks the list on the hat's label ("only the CI robot may wear this"), and if you are on it, you get the hat for one hour. Then it vanishes by itself.

Wearing the hat, you have the hat's permissions — not your own. And the office can give you the hat with a sticker on it: "today, only look, do not touch". The sticker can only take permissions away, never add any.

That is a role: the hat. The label is its trust policy. The one-hour pass comes from STS (Security Token Service). The sticker is a session policy.

🗺️ Diagram

flowchart LR
    who["🤖 user/ci-robot"]
    trust["🏷️ trust policy<br/>Principal: user/ci-robot<br/>Action: sts:AssumeRole"]
    sts["🎟️ STS AssumeRole<br/>ASIA… key + session token<br/>expires in 1 hour"]
    sess["🎩 assumed-role/ci-deployer/build-42"]
    perm["📝 ci-deploy policy<br/>ecr:PutImage …"]
    who -->|"1 may I wear it?"| trust -->|"2 yes"| sts --> sess
    sess -->|"3 acts with"| perm

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

❓ What

Role — an IAM identity with two policies: a trust policy (a resource policy on the role: who may assume it, with Principal) and permission policies (what the role may do). No password, no long-lived access key.
STS — AssumeRole returns an AccessKeyId (starting ASIA), a SecretAccessKey, a SessionToken and an Expiration. Default duration is 1 hour; you may ask for 15 minutes up to the role's maximum session duration (up to 12 hours). Role chaining (a role assuming another role) is limited to 1 hour.
Session ARN — arn:aws:sts::111122223333:assumed-role/ci-deployer/build-42: the role name plus a session name you choose — which is what CloudTrail records, so pick meaningful names.
Session policy — passed with AssumeRole (--policy or --policy-arns). Effective permissions = role policies ∩ session policy. It can only narrow.
Both sides must agree — the trust policy must allow the caller, and (across accounts, lesson 09) the caller's own policies must allow sts:AssumeRole on the role.

🤔 Why

Long-lived keys leak — in git, in logs, in laptops — and stay valid until someone notices. Temporary credentials expire by themselves, are tied to a named session, and never need rotating. Roles are how AWS services, CI systems, other accounts and people (lesson 10) should get access.

🔧 How (in this repo)

roles() in iam/demo.py checks the trust statement with matches() for ci-robot and for dipika, prints an example of temporary credentials, then calls decide() for the session — once with only the role policy, once with the read-only session policy added (session=).

🧪 Try it

python3 iam/demo.py roles
python3 - <<'EOF'
import sys; sys.path.insert(0, "iam"); from evaluate import decide, load, matches
trust = load("trust-ci-deployer")["Statement"][0]
role = "arn:aws:iam::111122223333:role/ci-deployer"
print("ci-robot may assume:", matches(trust, "sts:AssumeRole", role, {}, "arn:aws:iam::111122223333:user/ci-robot"))
print("partner may assume: ", matches(trust, "sts:AssumeRole", role, {}, "arn:aws:iam::444455556666:user/ci-robot"))
sess = "arn:aws:sts::111122223333:assumed-role/ci-deployer/build-43"
ci = [("ci-deploy", load("ci-deploy"))]
wide = [("session-s3", {"Version": "2012-10-17", "Statement": [{"Effect": "Allow", "Action": "s3:*", "Resource": "*"}]})]
print("in both:            ", decide(sess, "ecr:GetAuthorizationToken", "*", identity=ci, session=[("session-read-only", load("session-read-only"))])[0])
print("session only:       ", decide(sess, "s3:GetObject", "arn:aws:s3:::school-reports/term1.pdf", identity=ci, session=wide)[0])
EOF

On a real account (needs the AWS CLI and credentials):

aws iam create-role --role-name ci-deployer --assume-role-policy-document file://iam/policies/trust-ci-deployer.json
aws iam put-role-policy --role-name ci-deployer --policy-name ci-deploy --policy-document file://iam/policies/ci-deploy.json
aws sts assume-role --role-arn arn:aws:iam::111122223333:role/ci-deployer --role-session-name build-42 --duration-seconds 3600
aws sts assume-role --role-arn arn:aws:iam::111122223333:role/ci-deployer --role-session-name build-43 --policy file://iam/policies/session-read-only.json

✅ Verify — what you should see

roles prints 🎩 ci-robot … trust policy lets them ✅, 🎩 dipika … refuses 🚫, the example credentials line, then ✅ role session → ecr:PutImage ALLOW and 🚫 same session + read-only session policy IMPLICIT DENY — outside the session policy passed to AssumeRole. Your snippet prints True, False (same user name, different account — not the principal on the label), ALLOW (allowed by both) and IMPLICIT DENY (the session policy allows s3:*, but the role never had it — a session policy cannot add). On a real account, assume-role returns a Credentials block whose AccessKeyId starts with ASIA.

🏁 What you just proved

A role is worn, not owned: the trust policy picks who may wear it, STS makes the pass temporary, and a session policy can only shrink what the role already has.

⚠️ Common mistakes

"Principal": {"AWS": "*"} in a trust policy — anyone in any account may try
mixing up the trust policy (who) with the permission policy (what)
asking for 12-hour sessions "to be safe" — shorter is safer
session names like session1 — CloudTrail then cannot tell builds or people apart

🏭 Why this matters in production: in well-run AWS estates, nearly every caller is a role session — services, pipelines, other accounts and people via SSO — and the number of long-lived access keys is close to zero.

⏭️ Next

How does a robot that is not in AWS at all — GitHub Actions, a pod, a Lambda — get a hat without a stored key? Machine identities.

git checkout lesson-06-machine-identities

← Previoushow aws decides Next →machine identities

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