เป้าหมาย
ให้ GitHub Actions deploy CDK stack จากบท 02 ได้ โดยไม่มี access key เก็บใน GitHub เลย ใช้ OIDC ขอ credential ชั่วคราวทุกรอบ จำกัดว่า repo/branch/environment ไหนเท่านั้นที่ assume role ได้ และให้ prod ต้องมีคนกดอนุมัติ
ทำไมห้ามใช้ access key ใน CI
| access key ใน GitHub Secrets | OIDC |
|---|---|
| อายุยาวจนกว่าจะหมุน — หลุดครั้งเดียวใช้ได้เรื่อยๆ | credential อายุสั้น (ค่าเริ่มต้น 1 ชม.) หมดเองหลังจบ job |
| ใครแก้ workflow ได้ก็ขโมยไปได้ | trust policy จำกัดได้ถึงระดับ repo + branch + environment |
| ต้องหมุนคีย์เอง | ไม่มีอะไรให้หมุน |
| CloudTrail เห็นแค่ชื่อ IAM user | CloudTrail เห็น role session ต่อ run |
OIDC ทำงานอย่างไร
GitHub job ──ขอ JWT (id-token: write)──▶ GitHub OIDC (token.actions.githubusercontent.com)
│ JWT มี claim: aud=sts.amazonaws.com, sub=repo:ORG/REPO:ref:refs/heads/main ...
▼
AWS STS AssumeRoleWithWebIdentity ──ตรวจลายเซ็น + เทียบ trust policy──▶ credential ชั่วคราวรูปแบบ sub claim ที่ต้องรู้ (ค่าเริ่มต้นของ GitHub)
| job แบบไหน | sub |
|---|---|
| push ไป branch | repo:ORG/REPO:ref:refs/heads/main |
job ที่มี environment: prod |
repo:ORG/REPO:environment:prod (ไม่มี ref แล้ว!) |
| pull request | repo:ORG/REPO:pull_request |
| tag | repo:ORG/REPO:ref:refs/tags/v1.2.3 |
จุดพลาดอันดับหนึ่ง: ใส่
environment:ใน job แล้ว trust policy ยังเช็กref:refs/heads/main→Not authorized to perform sts:AssumeRoleWithWebIdentity
ออกแบบ role แบบ least privilege
- แยก role ตามหน้าที่:
gh-cdk-diff(อ่านอย่างเดียว ใช้กับ PR) และgh-cdk-deploy(ใช้กับ main/prod) - role ของ CI ไม่ต้องมีสิทธิ์สร้าง Lambda/DynamoDB เอง — ให้แค่
sts:AssumeRoleไปยัง role ที่ CDK bootstrap สร้างไว้ (cdk-hnb659fds-deploy-role-*,file-publishing-role,lookup-roleฯลฯ) สิทธิ์จริงอยู่ที่ CloudFormation execution role - อย่าใช้
StringLikeกับrepo:ORG/*— ทุก repo ในองค์กร (รวม fork ภายใน) จะ deploy prod ได้ - prod ควรอยู่บัญชีแยก + role แยกที่ trust เฉพาะ
environment:prod
Approval ก่อนขึ้น prod
GitHub → repo Settings → Environments → New environment prod → เปิด Required reviewers และจำกัด Deployment branches เป็น main → job ที่ระบุ environment: prod จะหยุดรอคนกด Approve และ sub จะเป็น environment:prod ที่ AWS เช็กได้
ลองเลย 🧪
ต้องมี repo บน GitHub ที่มีโค้ด notes-api จากบท 02 (ตัวอย่างใช้ my-org/notes-api — เปลี่ยนเป็นของคุณ) · ทำในบัญชี dev
ทดลอง A — สร้าง OIDC provider และ role
aws sso login --profile dev
export AWS_PROFILE=dev AWS_REGION=ap-southeast-1
ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
REPO="[my-org/notes-api]"
aws iam create-open-id-connect-provider \
--url https://token.actions.githubusercontent.com \
--client-id-list sts.amazonaws.comผลที่ควรเห็น:
{
"OpenIDConnectProviderArn": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
}(ถ้าได้ EntityAlreadyExists แปลว่ามีอยู่แล้ว ใช้ตัวเดิมได้ — หนึ่งบัญชีมี provider URL นี้ได้ตัวเดียว · ไม่ต้องใส่ thumbprint เพราะ AWS ตรวจใบรับรองของ GitHub ด้วย CA ที่เชื่อถือเอง)
trust policy — อนุญาตเฉพาะ branch main และ environment prod ของ repo นี้
cat > trust.json <<EOF
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": { "Federated": "arn:aws:iam::${ACCOUNT}: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:${REPO}:ref:refs/heads/main",
"repo:${REPO}:environment:prod"
] }
}
}]
}
EOF
cat > deploy-perms.json <<EOF
{
"Version": "2012-10-17",
"Statement": [{
"Sid": "AssumeCdkBootstrapRoles",
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::${ACCOUNT}:role/cdk-hnb659fds-*-${ACCOUNT}-ap-southeast-1"
}]
}
EOF
aws iam create-role --role-name gh-cdk-deploy \
--assume-role-policy-document file://trust.json --max-session-duration 3600 \
--query Role.Arn --output text
aws iam put-role-policy --role-name gh-cdk-deploy \
--policy-name assume-cdk-roles --policy-document file://deploy-perms.jsonผลที่ควรเห็น: arn:aws:iam::123456789012:role/gh-cdk-deploy — เอาค่านี้ไปใส่ GitHub Settings → Secrets and variables → Actions → Variables ชื่อ AWS_DEPLOY_ROLE_ARN (เป็น variable ไม่ใช่ secret ก็ได้ เพราะ ARN ไม่ใช่ความลับ)
ทดลอง B — workflow ไฟล์ .github/workflows/deploy.yml
name: deploy
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
concurrency:
group: deploy-${{ github.ref }}
cancel-in-progress: false # อย่ายกเลิก deploy กลางทาง stack จะค้าง
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v4
with: { node-version: 22, cache: npm }
- run: npm ci
- run: npm test
- run: npx cdk synth -c stage=dev > /dev/null
deploy-dev:
if: github.event_name == 'push'
needs: test
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v4
with: { node-version: 22, cache: npm }
- run: npm ci
- uses: aws-actions/configure-aws-credentials@v6
with:
role-to-assume: ${{ vars.AWS_DEPLOY_ROLE_ARN }}
aws-region: ap-southeast-1
- run: aws sts get-caller-identity
- run: npx cdk deploy -c stage=dev --require-approval never
deploy-prod:
needs: deploy-dev
runs-on: ubuntu-latest
environment: prod # หยุดรอ reviewer + sub กลายเป็น environment:prod
permissions:
id-token: write
contents: read
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v4
with: { node-version: 22, cache: npm }
- run: npm ci
- uses: aws-actions/configure-aws-credentials@v6
with:
role-to-assume: ${{ vars.AWS_DEPLOY_ROLE_ARN }}
aws-region: ap-southeast-1
- run: npx cdk diff -c stage=prod
- run: npx cdk deploy -c stage=prod --require-approval neverpush ขึ้น main แล้วดูแท็บ Actions
ผลที่ควรเห็น: job deploy-dev ขั้น aws sts get-caller-identity แสดง
"Arn": "arn:aws:sts::123456789012:assumed-role/gh-cdk-deploy/GitHubActions"และ deploy-prod ขึ้นสถานะ Waiting — review required จนกว่าจะกด Approve
ในงานจริง ใช้ role แยกสำหรับ prod ในบัญชี prod — ตัวอย่างนี้ใช้ role เดียวเพื่อให้แล็บสั้น
ทดลอง C — พิสูจน์ว่าล็อกได้จริง สร้าง branch feature/x แก้ใน branch นั้นให้ on.push.branches เป็น [main, feature/x] แล้ว push → job deploy-dev จะรันบน branch นี้
ผลที่ควรเห็น: ขั้น configure-aws-credentials ของ deploy-dev ล้มด้วย Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity — ถูกต้อง เพราะ sub เป็น ref:refs/heads/feature/x (ลบ branch ทิ้งหลังทดสอบ อย่า merge การแก้นี้เข้า main)
ดูใน CloudTrail ว่าใคร assume
aws cloudtrail lookup-events --region ap-southeast-1 \
--lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRoleWithWebIdentity \
--max-results 3 --query "Events[].[EventTime,Username]" --output tableเก็บกวาด (ถ้าไม่ใช้ต่อ)
npx cdk destroy -c stage=dev --force
npx cdk destroy -c stage=prod --force # ตาราง prod ถูก RETAIN — ลบเองในคอนโซล DynamoDB ถ้าตั้งใจ
aws iam delete-role-policy --role-name gh-cdk-deploy --policy-name assume-cdk-roles
aws iam delete-role --role-name gh-cdk-deploy
# OIDC provider ไม่คิดเงิน เก็บไว้ได้ ถ้าจะลบ (และไม่มี role อื่นใช้อยู่):
# aws iam delete-open-id-connect-provider --open-id-connect-provider-arn "arn:aws:iam::${ACCOUNT}:oidc-provider/token.actions.githubusercontent.com"ถ้าพัง: Credentials could not be loaded → ลืม permissions: id-token: write ใน job · Not authorized ... AssumeRoleWithWebIdentity → เทียบ sub จริงกับ trust policy (ชื่อ org/repo ตัวพิมพ์เล็ก-ใหญ่ต้องตรง) · current credentials could not be used to assume 'cdk-hnb659fds-deploy-role' → ARN ใน deploy-perms.json ผิด region/account หรือยังไม่ bootstrap
กับดักที่เจอบ่อย
| อาการ | สาเหตุ / แก้ |
|---|---|
| job prod assume ไม่ได้ แต่ dev ได้ | ใส่ environment: prod แล้ว sub เปลี่ยน — เพิ่ม repo:ORG/REPO:environment:prod ใน trust |
| ใครเปิด PR จาก fork ก็ deploy ได้ | trust ใช้ repo:ORG/* หรือ * — ระบุ repo และ ref/environment ให้ชัด |
ใส่ id-token: write ระดับ workflow ทุก job ได้ token หมด |
ใส่เฉพาะ job ที่ต้องคุย AWS |
workflow ถูกยกเลิกกลาง deploy แล้ว stack ค้าง UPDATE_IN_PROGRESS |
cancel-in-progress: false และอย่ากด Cancel ระหว่าง deploy |
role CI มี AdministratorAccess |
ให้แค่ assume CDK bootstrap roles และจำกัด CloudFormation execution policy ตอน bootstrap |
ยังมี AWS_ACCESS_KEY_ID ค้างใน Secrets |
ลบทิ้ง และ deactivate คีย์ของ IAM user นั้น |
สรุปจำง่าย
CI ห้ามมีคีย์ถาวร ใช้ OIDC — trust ล็อก
aud+subถึงระดับ repo/branch/environment — job ที่มี environment ได้subแบบenvironment:<ชื่อ>— role CI แค่ assume role ของ CDK — prod ต้องมี required reviewers