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

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

🤖 धडा 06 — Machine identities: secrets शिवाय बिल्ले

📍 तुम्ही इथे आहात: 12 पैकी धडा 06 · मागे: lesson-05-roles-sts · पुढे: lesson-07-conditions-abac

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

धडे 01–05, आणि त्यासोबत software ला साठवलेल्या key शिवाय AWS access कसा मिळतो: GitHub Actions ला OIDC federation मधून (trust-github-oidc.json), आणि हीच कल्पना AWS compute वर — EC2 instance profiles, Lambda execution roles, EKS IRSA आणि Pod Identity.

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

शाळेचा delivery robot 🤖 गावाच्या पलीकडच्या एका company कडून येतो. त्याला मास्टर चावीची प्रत देणे ही वाईट कल्पना आहे — robots हरवतात, चाव्यांच्या प्रती बनतात.

त्याऐवजी robot ची company त्याला प्रत्येक फेरीसाठी एक सही केलेले पत्र देते: "हा robot 7 आहे, आज main delivery मार्गावर काम करतो आहे". ओळखपत्र कार्यालयाला त्या company ची सही माहीत असते, ते पत्र वाचते, त्यावर लिहिलेला मार्ग तपासते, आणि robot ला एका तासाची टोपी देते. वेगळ्या मार्गासाठीचे पत्र, किंवा वेगळ्या company कडून आलेले पत्र, यांना काहीच मिळत नाही.

ते सही केलेले पत्र म्हणजे OIDC token. GitHub प्रत्येक workflow run साठी एक token सही करून देतो; AWS तो role च्या trust policy शी तपासतो आणि तात्पुरती credentials देतो. GitHub मध्ये कोणतेही secret कधीच साठवले जात नाही.

🗺️ आकृती

flowchart LR
    gh["⚙️ GitHub Actions run<br/>id-token: write"]
    tok["✉️ signed OIDC token<br/>aud: sts.amazonaws.com<br/>sub: repo:BaluRaut/school-app:ref:refs/heads/main"]
    sts["🎟️ STS AssumeRoleWithWebIdentity"]
    trust["🏷️ trust policy<br/>Federated: token.actions.githubusercontent.com<br/>checks aud + sub"]
    creds["🎩 1-hour credentials"]
    gh -->|"1 asks GitHub"| tok -->|"2 presents"| sts --> trust
    trust -->|"3 claims match"| creds
    trust -.->|"feature branch, fork"| no["🚫 refused"]

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

❓ काय

OIDC federation — तुम्ही IAM मध्ये एक identity provider नोंदवता (token.actions.githubusercontent.com); role ची trust policy त्याचे नाव "Principal": {"Federated": "arn:aws:iam::111122223333:oidc-provider/token.actions.githubusercontent.com"} असे sts:AssumeRoleWithWebIdentity सह घेते.
Claims म्हणजेच conditions — …:aud हे sts.amazonaws.com असायलाच हवे; …:sub सांगते कोणता repo आणि कोणता ref/environment: repo:OWNER/REPO:ref:refs/heads/main, repo:OWNER/REPO:pull_request, repo:OWNER/REPO:environment:prod. sub नेहमी तुमच्या repo ला बांधून ठेवा — त्याशिवाय कोणतीही GitHub repository तो role assume करू शकते.
AWS compute वर platform तुमच्यासाठी role credentials पोहोचवतो:
- EC2 — instance profile role ला गुंडाळून ठेवतो; SDK credentials instance metadata service मधून वाचतो (IMDSv2 बंधनकारक करा).
- Lambda / ECS tasks — execution role / task role.
- EKS — IRSA (cluster च्या OIDC provider मधून, role चे annotation असलेले service account) किंवा EKS Pod Identity (service account आणि role यांच्यातील association).
SDKs ची default credential chain हे सगळे आपोआप शोधते — code मध्ये कधीच keys नसतात.

🤔 का

Secret म्हणून साठवलेली CI access key म्हणजे दीर्घकाळाची मास्टर चावी, जी प्रत्येक workflow आणि प्रत्येक maintainer ला मिळू शकते, आणि ती हाताने rotate करावी लागते. Federation तिच्या जागी प्रत्येक run साठीचे credential आणते, जे एका तासात संपते आणि तुम्ही नाव दिलेल्या repo आणि branch साठीच चालते.

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

iam/demo.py मधला machines() token claims चे तीन संच बनवतो — main branch, एक feature branch आणि एक fork — आणि trust statement च्या conditions matches() मधून चालवतो. फक्त main ला role मिळतो.

🧪 करून पाहा

python3 iam/demo.py machines
python3 - <<'EOF'
import json, sys; sys.path.insert(0, "iam"); from evaluate import load, matches
trust = load("trust-github-oidc")["Statement"][0]
def token(sub, aud="sts.amazonaws.com"):
    return {"token.actions.githubusercontent.com:aud": aud, "token.actions.githubusercontent.com:sub": sub}
A = "sts:AssumeRoleWithWebIdentity"
print("main, right audience :", matches(trust, A, "*", token("repo:BaluRaut/school-app:ref:refs/heads/main")))
print("main, wrong audience :", matches(trust, A, "*", token("repo:BaluRaut/school-app:ref:refs/heads/main", aud="my-app")))
print("pull request         :", matches(trust, A, "*", token("repo:BaluRaut/school-app:pull_request")))
loose = json.loads(json.dumps(trust).replace("ref:refs/heads/main", "*"))
print("pull request, loose  :", matches(loose, A, "*", token("repo:BaluRaut/school-app:pull_request")))
EOF

खऱ्या account वर (AWS CLI आणि credentials लागतात) — GitHub ची एकदा नोंदणी करा, आणि या trust policy सह role बनवा:

aws iam create-open-id-connect-provider --url https://token.actions.githubusercontent.com --client-id-list sts.amazonaws.com
aws iam create-role --role-name github-deployer --assume-role-policy-document file://iam/policies/trust-github-oidc.json

आणि workflow मध्ये (GitHub ची बाजू):

permissions:
  id-token: write        # lets the job ask GitHub for an OIDC token
  contents: read
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::111122223333:role/github-deployer
      aws-region: ap-south-1
  - run: aws sts get-caller-identity

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

machines हे print करतो: ✅ … refs/heads/main → role assumed, 1-hour credentials आणि feature-x साठी व repo:someone/fork साठी 🚫 … refused. तुमचा snippet True, False (चुकीचा audience), False (pull request म्हणजे main नाही) आणि सैल केलेल्या repo:BaluRaut/school-app:* साठी True print करतो — wildcard असलेला sub कोणत्याही branch ला किंवा pull request ला deploy करू देतो. खऱ्या workflow मध्ये get-caller-identity assumed-role/github-deployer/… दाखवतो.

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

Machine साठवलेल्या secret ऐवजी सही केलेल्या, अल्पकाळाच्या token ने आपण कोण आहोत हे सिद्ध करू शकते — आणि कोणते runs पात्र ठरतात हे trust policy ची sub condition नेमके ठरवते.

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

sub condition नसणे, किंवा repo:OWNER/* — त्या owner चा कोणताही repo (किंवा त्याहून वाईट) deploy करू शकतो
"PRs चालावेत म्हणून" रुंद * सह StringLike — त्याऐवजी environment वापरा
workflow मध्ये permissions: id-token: write विसरणे
EC2 वर IMDSv1 चालू ठेवणे, किंवा AMIs आणि container images मध्ये keys भरून ठेवणे

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: "CI मध्ये दीर्घकाळाच्या keys नाहीत" हा आता audit चा नेहमीचा मुद्दा आहे. CI साठी OIDC, AWS compute साठी instance/task/execution roles, Kubernetes साठी IRSA किंवा Pod Identity — आणि credential report मधली keys ची संख्या शून्यावर येते.

⏭️ पुढे

त्या क्षणावर अवलंबून असणारे नियम — MFA, network, एखादा tag. Conditions आणि ABAC.

git checkout lesson-07-conditions-abac

🤖 Lesson 06 — Machine identities: badges without secrets

📍 You are here: Lesson 06 of 12 · Previous: lesson-05-roles-sts · Next: lesson-07-conditions-abac

📦 What's in this branch

Lessons 01–05, plus how software gets AWS access with no stored key: GitHub Actions through OIDC federation (trust-github-oidc.json), and the same idea on AWS compute — EC2 instance profiles, Lambda execution roles, EKS IRSA and Pod Identity.

🧒 Explain like I'm 5

The school's delivery robot 🤖 comes from a company across town. Giving it a copy of the master key is a bad idea — robots get lost, keys get copied.

Instead, the robot's company gives it a signed letter for each trip: "this is robot 7, working on the main delivery route, today". The ID office knows the company's signature, reads the letter, checks the route written on it, and gives the robot a one-hour hat. A letter for a different route, or from a different company, gets nothing.

That signed letter is an OIDC token. GitHub signs one for every workflow run; AWS checks it against the role's trust policy and issues temporary credentials. Nothing secret is ever stored in GitHub.

🗺️ Diagram

flowchart LR
    gh["⚙️ GitHub Actions run<br/>id-token: write"]
    tok["✉️ signed OIDC token<br/>aud: sts.amazonaws.com<br/>sub: repo:BaluRaut/school-app:ref:refs/heads/main"]
    sts["🎟️ STS AssumeRoleWithWebIdentity"]
    trust["🏷️ trust policy<br/>Federated: token.actions.githubusercontent.com<br/>checks aud + sub"]
    creds["🎩 1-hour credentials"]
    gh -->|"1 asks GitHub"| tok -->|"2 presents"| sts --> trust
    trust -->|"3 claims match"| creds
    trust -.->|"feature branch, fork"| no["🚫 refused"]

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

❓ What

OIDC federation — you register an identity provider in IAM (token.actions.githubusercontent.com); a role's trust policy names it as "Principal": {"Federated": "arn:aws:iam::111122223333:oidc-provider/token.actions.githubusercontent.com"} with sts:AssumeRoleWithWebIdentity.
Claims are conditions — …:aud must be sts.amazonaws.com; …:sub says which repo and which ref/environment: repo:OWNER/REPO:ref:refs/heads/main, repo:OWNER/REPO:pull_request, repo:OWNER/REPO:environment:prod. Always pin sub to your repo — without it, any GitHub repository could assume the role.
On AWS compute the platform delivers role credentials for you:
- EC2 — an instance profile wraps a role; the SDK reads credentials from the instance metadata service (require IMDSv2).
- Lambda / ECS tasks — an execution role / task role.
- EKS — IRSA (a service account annotated with a role, via the cluster's OIDC provider) or EKS Pod Identity (an association between a service account and a role).
The SDKs' default credential chain finds all of these automatically — code never contains keys.

🤔 Why

A CI access key stored as a secret is a long-lived master key that every workflow and every maintainer can reach, and it has to be rotated manually. Federation replaces it with a per-run credential that expires in an hour and only works for the repo and branch you named.

🔧 How (in this repo)

machines() in iam/demo.py builds three sets of token claims — the main branch, a feature branch and a fork — and runs the trust statement's conditions through matches(). Only main gets the role.

🧪 Try it

python3 iam/demo.py machines
python3 - <<'EOF'
import json, sys; sys.path.insert(0, "iam"); from evaluate import load, matches
trust = load("trust-github-oidc")["Statement"][0]
def token(sub, aud="sts.amazonaws.com"):
    return {"token.actions.githubusercontent.com:aud": aud, "token.actions.githubusercontent.com:sub": sub}
A = "sts:AssumeRoleWithWebIdentity"
print("main, right audience :", matches(trust, A, "*", token("repo:BaluRaut/school-app:ref:refs/heads/main")))
print("main, wrong audience :", matches(trust, A, "*", token("repo:BaluRaut/school-app:ref:refs/heads/main", aud="my-app")))
print("pull request         :", matches(trust, A, "*", token("repo:BaluRaut/school-app:pull_request")))
loose = json.loads(json.dumps(trust).replace("ref:refs/heads/main", "*"))
print("pull request, loose  :", matches(loose, A, "*", token("repo:BaluRaut/school-app:pull_request")))
EOF

On a real account (needs the AWS CLI and credentials) — register GitHub once, create the role with this trust policy:

aws iam create-open-id-connect-provider --url https://token.actions.githubusercontent.com --client-id-list sts.amazonaws.com
aws iam create-role --role-name github-deployer --assume-role-policy-document file://iam/policies/trust-github-oidc.json

and in the workflow (GitHub side):

permissions:
  id-token: write        # lets the job ask GitHub for an OIDC token
  contents: read
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::111122223333:role/github-deployer
      aws-region: ap-south-1
  - run: aws sts get-caller-identity

✅ Verify — what you should see

machines prints ✅ … refs/heads/main → role assumed, 1-hour credentials and 🚫 … refused for feature-x and for repo:someone/fork. Your snippet prints True, False (wrong audience), False (a pull request is not main) and True for the loosened repo:BaluRaut/school-app:* — a wildcard sub lets any branch or pull request deploy. In a real workflow, get-caller-identity shows assumed-role/github-deployer/….

🏁 What you just proved

A machine can prove who it is with a signed, short-lived token instead of a stored secret — and the trust policy's sub condition decides exactly which runs qualify.

⚠️ Common mistakes

no sub condition, or repo:OWNER/* — any repo of that owner (or worse) can deploy
StringLike with a broad * "to make PRs work" — use an environment instead
forgetting permissions: id-token: write in the workflow
leaving IMDSv1 enabled on EC2, or baking keys into AMIs and container images

🏭 Why this matters in production: "no long-lived keys in CI" is now a standard audit item. OIDC for CI, instance/task/execution roles for AWS compute, IRSA or Pod Identity for Kubernetes — and the credential-report key count goes to zero.

⏭️ Next

Rules that depend on the moment — MFA, the network, a tag. Conditions and ABAC.

git checkout lesson-07-conditions-abac

← Previousroles sts Next →conditions abac

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