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

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

🪪 धडा 06 — Secrets आणि least privilege: कुरिअरचा बॅज

📍 तुम्ही इथे आहात: 12 पैकी धडा 06 · मागे: lesson-05-artifacts-reports · पुढे: lesson-07-build-push-image

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

धडे 01–05, आणि mailroom सुरक्षित ठेवणारा नियम — courier शाळेची मुख्य किल्ली बाळगत नाही. खऱ्या files:

iam/github-oidc-trust-policy.json — CI ची टोपी कोण घालू शकते: या repo च्या main branch चे runs
iam/ci-role-policy.json — ती टोपी काय करू शकते: एका ECR repository मध्ये push, एका cluster चे describe
.github/workflows/ship.yml आणि ci.yml — permissions: blocks आणि 🪪 show the badge step
.circleci/config.yml, .gitlab-ci.yml, Jenkinsfile — contexts, id_tokens, withAWS

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

फोटोकॉपी ठेवण्यासाठी courier robot 📮 ला लॉकर रूम 🏦 मध्ये जायचे आहे. आळशी मार्ग: त्याला मुख्य किल्ली 🔑 द्या — ती संपूर्ण इमारत उघडते, तिला संपण्याची तारीख नाही, आणि robot ने ती कॉरिडॉरमध्ये टाकली तर ज्याला सापडेल तो शाळेचा मालक होतो. CI मध्ये ती किल्ली म्हणजे साठवलेली AWS access key.

शाळेचा मार्ग: robot एक बॅज 🪪 घालतो ज्यावर लिहिलेले असते "या शाळेचा courier, या मार्गावर". पहारेकरी तो पाहुण्यांच्या यादीशी जुळवून पाहतो — शाळेच्या office ने सही केली आहे का? या दारासाठी आहे का? या मार्गासाठी? — आणि एक डे पास 🎫 देतो जो एकच लॉकर उघडतो आणि सुमारे एका तासात चालणे बंद होतो. तेच म्हणजे OIDC: GitHub बॅजवर सही करते, AWS STS हा पहारेकरी, trust policy म्हणजे पाहुण्यांची यादी, permissions policy म्हणजे पास उघडू शकणाऱ्या दारांची यादी.

Courier च्या खिशात आणखी दोन गोष्टी. Variables म्हणजे सूचना फलकावर लावलेल्या चिठ्ठ्या — region, repository चे नाव — कोणीही वाचू शकते. Secrets म्हणजे सीलबंद पाकिटे, जी mailroom ती छापत असलेल्या logs मध्ये काळी करते. पण marker फक्त नेमका मजकूरच ओळखतो; पत्राची तिरकी फोटोकॉपी काढा (base64 करा, तुकडे करा, file मध्ये लिहा) आणि marker चुकतो.

🗺️ आकृती

flowchart LR
    job["📮 push job<br/>permissions: id-token: write"]
    gh["🏫 GitHub OIDC<br/>signs a short-lived token"]
    sts["🛂 AWS STS<br/>checks the trust policy (WHO)<br/>aud + sub"]
    ecr["🏦 ECR hello-courier<br/>ci-role-policy (WHAT): one repo, one cluster"]
    job -->|"1 ask for a badge"| gh
    gh -->|"2 signed ID token"| job
    job -->|"3 show the badge"| sts
    sts -->|"4 day pass: temporary credentials, this job only"| ecr

❓ काय

Secret = CI system encrypted स्वरूपात ठेवते, save केल्यावर लपवते आणि logs मध्ये mask (***) करते असे मूल्य: ${{ secrets.NAME }}. Variable = साधी configuration, Settings मध्ये वाचता येते, जशीच्या तशी छापली जाते: ${{ vars.NAME }}. या repo च्या चार AWS settings variables आहेत — role ARN आणि region हे पत्ते आहेत, किल्ल्या नाहीत.
Masking = log मध्ये नेमक्या string ची अदलाबदल. echo $SECRET *** छापते, पण file, artifact किंवा URL मध्ये लिहिलेले, किंवा base64 मधून pipe केलेले मूल्य तरीही leak च आहे.
permissions: = run चा स्वतःचा GITHUB_TOKEN काय करू शकतो; कोणतीही permission लिहिली की न लिहिलेल्या none होतात. id-token: write म्हणजे "OIDC token मागू शकतो" — "write" मागण्याबद्दल आहे, कुठे लिहिण्याबद्दल नाही.
Trust policy = role कोण assume करू शकते ते, STS token च्या aud आणि sub claims शी जुळवून कोण ते तपासते. Permissions policy = role काय करू शकते.

🧠 मुख्य किल्ली विरुद्ध बॅज

	🔑 साठवलेल्या access keys	🪪 बॅज → 🎫 डे पास (OIDC)
ते कुठे राहते	secret मध्ये, कोणी rotate करेपर्यंत	कुठेच नाही — प्रत्येक job साठी नवे बनते
ते leak झाले तर	लक्षात येऊन rotate होईपर्यंत वैध	तासाभरात संपते; trust policy च्या बाहेर निरुपयोगी
ते काय उघडते	IAM user कडे जे काही आहे ते	फक्त role च्या policy मध्ये लिहिलेले

🤔 का

Leak झालेली CI credentials ही एक नेहमीची घटना आहे: log मध्ये छापलेली key, artifact मध्ये copy झालेली, किंवा fork मधल्या workflow ने वाचलेली. साठवलेली key rotate करावी लागते, आणि प्रत्यक्षात क्वचितच केली जाते. OIDC साठवलेली key काढून टाकते, आणि दोन IAM files नुकसानाचा परिघ एका repository आणि एका cluster पुरता लहान करतात. हे AWS शाळेचे "robots साठी बॅज" आहे, EC2 instance ऐवजी GitHub runner सह, आणि त्याचा IAM स्वच्छतेचा धडा pipeline ला लावलेला.

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

Run च्या स्वतःच्या token साठी least privilege. ci.yml फक्त contents: read देते; ship.yml बॅजला लागणारी एक गोष्ट जोडते:

permissions:
  contents: read
  id-token: write           # lesson 06: lets this run ask for an OIDC badge — no stored AWS keys

बॅजची step. push job फक्त variable अस्तित्वात असेल तेव्हाच चालतो (if: vars.AWS_ROLE_ARN != '' — AWS नसलेला fork तो वगळतो आणि हिरवाच राहतो). पाच ओळी, चार पायऱ्या:

      - name: 🪪 show the badge, get a day pass (OIDC → temporary credentials)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
          aws-region: ${{ vars.AWS_REGION }}

id-token: write ने परवानगी मिळाल्यावर, action GitHub कडे token मागते; GitHub aud = sts.amazonaws.com आणि sub = repo:BaluRaut/learn-cicd-school:ref:refs/heads/main असलेल्या token वर सही करते.
Action तो token आणि role ARN घेऊन STS AssumeRoleWithWebIdentity call करते.
STS GitHub ची सही तपासते, मग role ची trust policy तपासते: aud बरोबर आहे का, sub जुळतो का?
STS temporary credentials परत देते (key, secret, session token — default नुसार एक तास), जी action फक्त या job साठी environment variables म्हणून export करते. Job संपला, credentials गेली.

कोण — trust policy, iam/github-oidc-trust-policy.json:

      "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" },
        "StringLike":   { "token.actions.githubusercontent.com:sub": "repo:BaluRaut/learn-cicd-school:ref:refs/heads/main" }
      }

sub ची ओळ हाच संपूर्ण मुद्दा आहे: दुसऱ्या repository मधला, किंवा याच repo च्या feature branch वरचा run वेगळा sub दाखवतो आणि नाकारला जातो. तुमच्या fork चे runs repo:<your-user>/learn-cicd-school:… घेऊन येतात, म्हणून तुमच्या fork साठीच्या role मध्ये तिथे तुमचे नाव हवे.

काय — permissions policy, iam/ci-role-policy.json (मधल्या statement मधल्या सात ecr: actions वगळल्या आहेत):

    { "Sid": "EcrLogin", "Effect": "Allow", "Action": "ecr:GetAuthorizationToken", "Resource": "*" },
    {
      "Sid": "EcrPushOneRepo",
      …
      "Resource": "arn:aws:ecr:ap-south-1:123456789012:repository/hello-courier"
    },
    { "Sid": "FindTheCluster", "Effect": "Allow", "Action": "eks:DescribeCluster",
      "Resource": "arn:aws:eks:ap-south-1:123456789012:cluster/school-eks" }

GetAuthorizationToken म्हणजे registry login, आणि तो रचनेनुसारच संपूर्ण account साठी असतो, म्हणून त्याला * लागतो. वगळलेल्या actions layers upload करतात आणि image ठेवतात — repositories delete किंवा create करणारे काहीही नाही — आणि उरलेली प्रत्येक ओळ एकच repository किंवा एकच cluster नावाने सांगते. ecr:* नाही, eks:* नाही, iam:* नाही.

🔁 हेच CircleCI मध्ये

      - test:                            # NO context: tests never see cloud credentials
      - build-and-push:
          context: school-cicd
          requires: [test]

Context म्हणजे organization settings मधला environment variables चा नाव दिलेला संच; जे jobs तो यादीत लिहितात त्यांनाच तो मिळतो. build-and-push मध्ये, role_arn: ${AWS_ROLE_ARN} सह aws-cli/setup CircleCI च्या स्वतःच्या OIDC token ने तीच बॅजची अदलाबदल करते.

🦊 हेच GitLab CI मध्ये

  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.com

id_tokens: मुळे GitLab बॅज $GITLAB_OIDC_TOKEN मध्ये बनवते; मग .aws-badge anchor चे before_script हाताने aws sts assume-role-with-web-identity चालवते आणि तीन credentials export करते. <<: *aws-badge merge करणाऱ्या jobs नाच ते मिळते — test job ला नाही.

🎩 हेच Jenkins मध्ये

        withAWS(credentials: 'aws-school-cicd', region: env.AWS_REGION) {

Jenkins credentials स्वतःच्या store मध्ये ठेवते आणि withAWS (Pipeline: AWS Steps plugin) ती फक्त block च्या आतच उघड करते. Jenkins साठी कोणतीही hosted सेवा आपोआप बॅजवर सही करत नाही, म्हणून प्रामाणिक setup म्हणजे आधीच IAM role असलेल्या EC2 instance किंवा pod वरचा agent — पुन्हा AWS शाळेचा धडा 05.

🧪 करून पाहा

# 1) read the two lists — no AWS needed
cat iam/github-oidc-trust-policy.json iam/ci-role-policy.json   # WHO: aud + sub · WHAT: one repo, one cluster

# 2) what your fork (lesson 03) carries: no variables → push/deploy skipped; no secrets → no stored keys
gh variable list && gh secret list

# 3) OPTIONAL — needs an AWS account (ECR storage and transfer may cost a little)
ACCOUNT=$(aws sts get-caller-identity --query Account --output text); ME=$(gh api user --jq .login)
aws iam create-open-id-connect-provider --url https://token.actions.githubusercontent.com --client-id-list sts.amazonaws.com   # older AWS CLIs also insist on --thumbprint-list
# drop the "_comment" line (IAM accepts only known keys); put YOUR account id and GitHub user in
grep -v '"_comment"' iam/github-oidc-trust-policy.json | sed -e "s/123456789012/$ACCOUNT/" -e "s|repo:BaluRaut/|repo:$ME/|" > /tmp/trust.json
grep -v '"_comment"' iam/ci-role-policy.json | sed "s/123456789012/$ACCOUNT/" > /tmp/perms.json
aws iam create-role --role-name learn-cicd-school-ci --assume-role-policy-document file:///tmp/trust.json
aws iam put-role-policy --role-name learn-cicd-school-ci --policy-name ci --policy-document file:///tmp/perms.json
aws ecr create-repository --repository-name hello-courier --region ap-south-1 --image-scanning-configuration scanOnPush=true
gh variable set AWS_ROLE_ARN --body "arn:aws:iam::$ACCOUNT:role/learn-cicd-school-ci"
gh variable set AWS_REGION --body ap-south-1 && gh variable set ECR_REPOSITORY --body hello-courier
# leave EKS_CLUSTER unset until lesson 10: the next push to main runs "push to ECR"; deploy stays skipped

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

"सुरक्षित राहावे म्हणून" role ARN किंवा region secret म्हणून ठेवणे — ते पत्ते आहेत; मग masking उपयोगी log ओळी लपवते, आणि job-level if: vars तपासू शकतो पण secrets नाही
sub condition नसलेली (किंवा मोठे wildcard असलेली) trust policy — मग sts.amazonaws.com साठी token मिळवू शकणारी कोणतीही GitHub repository role assume करू शकते
log मधल्या *** ला सुरक्षिततेचा पुरावा समजणे — file, artifact, URL मध्ये लिहिलेले, किंवा base64 मधून pipe केलेले secret mask ला चुकवून निघून जाते

⏭️ पुढे

डे पास हातात घेऊन courier फोटोकॉपी मशीनकडे जातो: डबा build करा, तो सुरू होतो हे सिद्ध करा, त्यावर commit चा ठसा लिहा, लॉकरमध्ये ठेवा. 📦

git checkout lesson-07-build-push-image

🪪 Lesson 06 — Secrets & least privilege: the courier's badge

📍 You are here: Lesson 06 of 12 · Previous: lesson-05-artifacts-reports · Next: lesson-07-build-push-image

📦 What's in this branch

Lessons 01–05, plus the rule that keeps the mailroom safe — the courier does not carry the school's master key. Real files:

iam/github-oidc-trust-policy.json — WHO may wear the CI hat: runs of this repo's main branch
iam/ci-role-policy.json — WHAT the hat may do: push to one ECR repository, describe one cluster
.github/workflows/ship.yml and ci.yml — the permissions: blocks and the 🪪 show the badge step
.circleci/config.yml, .gitlab-ci.yml, Jenkinsfile — contexts, id_tokens, withAWS

🧒 Explain like I'm 5

The courier robot 📮 has to get into the locker room 🏦 to file the photocopies. The lazy way: give it the master key 🔑 — it opens the whole building, has no expiry date, and if the robot drops it in the corridor, whoever finds it owns the school. In CI that key is a stored AWS access key.

The school way: the robot wears a badge 🪪 saying "courier of THIS school, on THIS route". The guard checks it against a guest list — signed by the school office? meant for this door? this route? — and hands over a day pass 🎫 that opens one locker and stops working in about an hour. That is OIDC: GitHub signs the badge, AWS STS is the guard, the trust policy is the guest list, the permissions policy is the list of doors the pass opens.

Two more things in the courier's pocket. Variables are notes pinned on the notice board — a region, a repository name — anyone may read them. Secrets are sealed envelopes the mailroom blacks out in the logs it prints. But the marker only recognizes the exact text; photocopy the letter sideways (base64 it, split it, write it to a file) and the marker misses it.

🗺️ Diagram

flowchart LR
    job["📮 push job<br/>permissions: id-token: write"]
    gh["🏫 GitHub OIDC<br/>signs a short-lived token"]
    sts["🛂 AWS STS<br/>checks the trust policy (WHO)<br/>aud + sub"]
    ecr["🏦 ECR hello-courier<br/>ci-role-policy (WHAT): one repo, one cluster"]
    job -->|"1 ask for a badge"| gh
    gh -->|"2 signed ID token"| job
    job -->|"3 show the badge"| sts
    sts -->|"4 day pass: temporary credentials, this job only"| ecr

❓ What

Secret = a value the CI system stores encrypted, hides after saving and masks (***) in logs: ${{ secrets.NAME }}. Variable = plain configuration, readable in Settings, printed as-is: ${{ vars.NAME }}. This repo's four AWS settings are variables — a role ARN and a region are addresses, not keys.
Masking = exact-string replacement in the log. echo $SECRET prints ***, but the value written to a file, an artifact or a URL, or piped through base64, is still a leak.
permissions: = what the run's own GITHUB_TOKEN may do; listing any permission sets the unlisted ones to none. id-token: write means "may request an OIDC token" — the "write" is about asking, not writing anywhere.
Trust policy = WHO may assume the role, checked by STS against the token's aud and sub claims. Permissions policy = WHAT the role may do.

🧠 Master key vs badge

	🔑 stored access keys	🪪 badge → 🎫 day pass (OIDC)
where it lives	in a secret, until someone rotates it	nowhere — minted per job
if it leaks	valid until noticed and rotated	expires within the hour; useless outside the trust policy
what it opens	whatever the IAM user has	only what the role's policy lists

🤔 Why

Leaked CI credentials are a classic incident: a key printed in a log, copied into an artifact, or read by a workflow from a fork. A stored key also has to be rotated, and in practice rarely is. OIDC removes the stored key, and the two IAM files shrink the blast radius to one repository and one cluster. It is the AWS school's "badges for robots" with a GitHub runner instead of an EC2 instance, plus its IAM hygiene lesson applied to a pipeline.

🔧 How (in this repo)

Least privilege for the run's own token. ci.yml grants only contents: read; ship.yml adds the one thing the badge needs:

permissions:
  contents: read
  id-token: write           # lesson 06: lets this run ask for an OIDC badge — no stored AWS keys

The badge step. The push job runs only when the variable exists (if: vars.AWS_ROLE_ARN != '' — a fork without AWS skips it and stays green). Five lines, four steps:

      - name: 🪪 show the badge, get a day pass (OIDC → temporary credentials)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
          aws-region: ${{ vars.AWS_REGION }}

Allowed by id-token: write, the action asks GitHub for a token; GitHub signs one with aud = sts.amazonaws.com and sub = repo:BaluRaut/learn-cicd-school:ref:refs/heads/main.
The action calls STS AssumeRoleWithWebIdentity with that token and the role ARN.
STS verifies GitHub's signature, then checks the role's trust policy: does aud equal, does sub match?
STS returns temporary credentials (key, secret, session token — one hour by default), which the action exports as environment variables for this job only. Job over, credentials gone.

WHO — the trust policy, iam/github-oidc-trust-policy.json:

      "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" },
        "StringLike":   { "token.actions.githubusercontent.com:sub": "repo:BaluRaut/learn-cicd-school:ref:refs/heads/main" }
      }

The sub line is the whole point: a run from another repository, or from a feature branch of this one, presents a different sub and is refused. Your fork's runs carry repo:<your-user>/learn-cicd-school:…, so a role for your fork needs your name there.

WHAT — the permissions policy, iam/ci-role-policy.json (the middle statement's seven ecr: actions elided):

    { "Sid": "EcrLogin", "Effect": "Allow", "Action": "ecr:GetAuthorizationToken", "Resource": "*" },
    {
      "Sid": "EcrPushOneRepo",
      …
      "Resource": "arn:aws:ecr:ap-south-1:123456789012:repository/hello-courier"
    },
    { "Sid": "FindTheCluster", "Effect": "Allow", "Action": "eks:DescribeCluster",
      "Resource": "arn:aws:eks:ap-south-1:123456789012:cluster/school-eks" }

GetAuthorizationToken is the registry login and is account-wide by design, so it needs *. The elided actions upload layers and put an image — nothing that deletes or creates repositories — and each remaining line names one repository or one cluster. No ecr:*, no eks:*, no iam:*.

🔁 The same thing in CircleCI

      - test:                            # NO context: tests never see cloud credentials
      - build-and-push:
          context: school-cicd
          requires: [test]

A context is a named bundle of environment variables in the organization settings; only the jobs that list it receive it. Inside build-and-push, aws-cli/setup with role_arn: ${AWS_ROLE_ARN} does the same badge exchange with CircleCI's own OIDC token.

🦊 The same thing in GitLab CI

  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.com

id_tokens: makes GitLab mint the badge into $GITLAB_OIDC_TOKEN; the .aws-badge anchor's before_script then runs aws sts assume-role-with-web-identity by hand and exports the three credentials. Only jobs that merge in <<: *aws-badge get it — the test job does not.

🎩 The same thing in Jenkins

        withAWS(credentials: 'aws-school-cicd', region: env.AWS_REGION) {

Jenkins keeps credentials in its own store and withAWS (Pipeline: AWS Steps plugin) exposes them only inside the block. Nothing hosted signs a badge for Jenkins out of the box, so the honest setup is an agent on an EC2 instance or pod that already holds an IAM role — AWS school lesson 05 again.

🧪 Try it

# 1) read the two lists — no AWS needed
cat iam/github-oidc-trust-policy.json iam/ci-role-policy.json   # WHO: aud + sub · WHAT: one repo, one cluster

# 2) what your fork (lesson 03) carries: no variables → push/deploy skipped; no secrets → no stored keys
gh variable list && gh secret list

# 3) OPTIONAL — needs an AWS account (ECR storage and transfer may cost a little)
ACCOUNT=$(aws sts get-caller-identity --query Account --output text); ME=$(gh api user --jq .login)
aws iam create-open-id-connect-provider --url https://token.actions.githubusercontent.com --client-id-list sts.amazonaws.com   # older AWS CLIs also insist on --thumbprint-list
# drop the "_comment" line (IAM accepts only known keys); put YOUR account id and GitHub user in
grep -v '"_comment"' iam/github-oidc-trust-policy.json | sed -e "s/123456789012/$ACCOUNT/" -e "s|repo:BaluRaut/|repo:$ME/|" > /tmp/trust.json
grep -v '"_comment"' iam/ci-role-policy.json | sed "s/123456789012/$ACCOUNT/" > /tmp/perms.json
aws iam create-role --role-name learn-cicd-school-ci --assume-role-policy-document file:///tmp/trust.json
aws iam put-role-policy --role-name learn-cicd-school-ci --policy-name ci --policy-document file:///tmp/perms.json
aws ecr create-repository --repository-name hello-courier --region ap-south-1 --image-scanning-configuration scanOnPush=true
gh variable set AWS_ROLE_ARN --body "arn:aws:iam::$ACCOUNT:role/learn-cicd-school-ci"
gh variable set AWS_REGION --body ap-south-1 && gh variable set ECR_REPOSITORY --body hello-courier
# leave EKS_CLUSTER unset until lesson 10: the next push to main runs "push to ECR"; deploy stays skipped

⚠️ Common mistakes

storing the role ARN or region as a secret "to be safe" — they are addresses; masking then hides useful log lines, and a job-level if: can test vars but not secrets
a trust policy without the sub condition (or with a wide wildcard) — any GitHub repository able to obtain a token for sts.amazonaws.com could then assume the role
treating *** in the log as proof of safety — a secret written to a file, an artifact, a URL, or piped through base64 walks past the mask

⏭️ Next

Day pass in hand, the courier walks to the photocopier: build the box, prove it starts, write the commit's fingerprint on it, file it in the locker. 📦

git checkout lesson-07-build-push-image

← Previousartifacts reports Next →build push image

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