IAM 的心智模型

IAM（Identity and Access Management）是雲端平台用來回答「某個身分能不能對某個資源做某件事」的授權系統。它把授權拆成三個獨立的零件：identity（身分，發起動作的主體）、policy（政策，描述允許或拒絕的規則）、role（角色，一組可以被臨時取得的權限集合）。理解這三者的分工，是後面所有憑證決策的前提。

identity：長期主體 vs 臨時假扮

identity 分兩類，這個區分在後面設計權限邊界時會反覆用到。一類是 user，代表一個長期存在的主體，通常對應到一個真人或一個固定的服務帳號，本身可以持有長期憑證（密碼或 access key）。另一類是 role，代表一組權限的暫時授予 — 沒有自己的長期密碼，而是讓某個被信任的身分「假扮（assume）」成它、換取一段有時效的臨時憑證。

把 identity 想成「護照」和「通行證」的差別：user 是護照，長期有效、全程攜帶；role 是通行證，到了管制區域臨時換發、離開就失效。多數安全事故源自於把通行證當護照用 — 某個 role 被長期假扮且從未被撤回，或某個 user 持有永不輪替的 access key。

policy：描述「允許對什麼做什麼」

policy 是貼在 user 或 role 上的規則文件，列出 Action（能做什麼，如 s3:GetObject）、Resource（對哪個資源，如特定 bucket 的 ARN）、Effect（Allow 或 Deny）。一條 policy 可以包含多個 statement，每條 statement 描述一組操作許可。

1# 最小權限範例：CI 只能讀寫特定 bucket，不給整個 S3
2data "aws_iam_policy_document" "ci_artifacts" {
3  statement {
4    effect    = "Allow"
5    actions   = ["s3:GetObject", "s3:PutObject"]
6    resources = ["arn:aws:s3:::myapp-artifacts/*"]
7  }
8}

這段 policy 只允許對 myapp-artifacts 這一個 bucket 做讀寫。如果寫成 resources = ["*"]，同一把身分被攻破時，攻擊者就能讀寫帳號內所有 bucket — 差別不在語法，在 Resource 欄位收到多緊。

role：臨時身分的載體

role 本身不持有長期密碼。它靠 trust policy（信任政策）定義「誰能假扮我」，靠 permissions policy 定義「假扮後能做什麼」。trust policy 和 permissions policy 是兩份獨立的文件，分別回答「誰進得來」與「進來後能做什麼」。

 1# trust policy：只允許 ECS 服務假扮此 role
 2data "aws_iam_policy_document" "ecs_trust" {
 3  statement {
 4    actions = ["sts:AssumeRole"]
 5    principals {
 6      type        = "Service"
 7      identifiers = ["ecs-tasks.amazonaws.com"]
 8    }
 9  }
10}
11
12resource "aws_iam_role" "api_task" {
13  name               = "api-task-prod"
14  assume_role_policy = data.aws_iam_policy_document.ecs_trust.json
15}

trust policy 裡的 principals 決定能進門的身分。上面這段把進門權限限給 ECS 服務本身，意味著只有跑在 ECS 上的 task 才能取得這個 role 的臨時憑證 — 一個在本地筆電跑的程式呼叫 AssumeRole 會被拒絕。

最小權限：持續收斂而非一次設定

最小權限（least privilege）是貫穿整套系統的設計原則：一個身分只應該拿到完成它本職工作所需的最小權限集合。多一個 action 是多一條攻擊面，多一個 resource 是多一個爆炸半徑。

最小權限是持續收斂的過程，而非一次設定就結束的靜態狀態。服務初期常為了快速上線給寬鬆權限 — 一個新的 ECS task role 掛上 AmazonS3FullAccess 讓它能跑起來，半年後這個 role 實際只用了 s3:GetObject 和 s3:PutObject 兩個 action、針對一個 bucket，但 policy 裡寫的還是全部 S3 操作對所有 bucket。

收斂的工具是 access analyzer。AWS IAM Access Analyzer 能分析 CloudTrail 日誌，列出某個 role 在過去 N 天內實際用了哪些 action 與 resource，據此產出一份建議的最小 policy。用它的步驟是：開著寬 policy 跑一段時間 → 用 access analyzer 產出實際使用清單 → 把 policy 收斂到這份清單 → 確認服務仍正常。

 1# 產出建議 policy：分析 api-task-prod role 過去 90 天的實際用量
 2aws accessanalyzer generate-policy \
 3  --policy-generation-details '{
 4    "principalArn": "arn:aws:iam::123456789012:role/api-task-prod",
 5    "cloudTrailDetails": {
 6      "trailArn": "arn:aws:cloudtrail:ap-northeast-1:123456789012:trail/main",
 7      "startTime": "2026-03-01T00:00:00Z",
 8      "endTime": "2026-06-01T00:00:00Z"
 9    }
10  }'

一個快速的盤點方式：列出所有掛著 AdministratorAccess、PowerUserAccess、*FullAccess 這類寬鬆 managed policy 的 role，每個命中都問一次「這個 role 確實需要這些權限嗎」。CI role 的 policy 裡出現 *:* 更是明確的收斂目標。

長期 access key 的風險

長期 access key 是一組沒有到期時間的靜態憑證（access key ID + secret），任何持有它的人或程式都能以對應身分的全部權限呼叫 API，直到有人手動撤銷為止。它最大的問題是「沒有時效」這個性質本身，會在三個方向上累積風險，而且風險隨團隊規模與時間單調上升。

散落

長期 key 為了被程式使用，會被複製進 .env 檔、CI 設定、本機 ~/.aws/credentials、Slack 訊息、甚至誤推進 git 歷史。每多一個副本就多一個外洩點。一把 key 在半年內可能被貼到六個地方 — 部署腳本、兩個 CI 平台的環境變數、某台共用跳板機的 profile、一封交接信、一位已離職同事的筆電 — 而這六個副本沒有任何中央清單能列舉。

權限過大

因為輪替麻煩，團隊傾向給一把 key 配足夠寬的權限「一次搞定」。建立時圖方便掛了 AdministratorAccess，打算「等穩定了再收斂」，但那天從來沒有到來。於是一把本來只該讀 artifact 的 key 同時握有刪除 production 資料庫的能力。

難以輪替

輪替一把長期 key 意味著找出所有副本、同步替換、確認沒有遺漏。這個成本高到讓多數團隊選擇拖延，於是 key 的有效期變成「無限」，外洩後的曝險窗口也跟著變成無限。用一個問題辨認風險：能不能在五分鐘內回答「這把 key 被用在哪些地方、上次輪替是什麼時候」？答不出來，它就已經是技術債。

常見的散落路徑：部署腳本使用的 admin key 留在 CI 環境變數，建立者離職後沒人知道這把 key 的存在與權限範圍。這類情境的風險在於外洩後沒有手段限制影響範圍 — key 的權限有多大，影響範圍就有多大。用 credential report 定期盤點帳號內所有 access key 的建立時間與使用時間，見模組負一：還沒有 infra 的環境。

長期憑證風險的實際規模可以從兩個案例看到。Snowflake 2024 事件中，攻擊者利用外洩的長期憑證登入缺少 MFA 的客戶環境，執行大量資料匯出，造成跨客戶的資料竊取與勒索（見 Snowflake 2024：憑證濫用與資料竊取）。LastPass 2022 事件則顯示備份路徑的憑證管理缺口會讓影響範圍沿信任鏈擴散——開發環境取得的資訊被用來存取雲端備份，整條路徑的金鑰隔離不足是根因（見 LastPass 2022：備份路徑與鏈式入侵）。兩個案例的共同教訓是：長期憑證的風險不止於外洩本身，而在於外洩後缺乏限制影響範圍的機制。

OIDC：給 CI/CD 的短期憑證

OIDC（OpenID Connect）聯合讓 CI/CD 平台用一段每次執行才簽發、幾分鐘後就失效的短期憑證取代長期 key，從根本上消掉「靜態密鑰散落」這個問題。它的運作方式是建立信任關係：雲端帳號信任某個外部 identity provider（如 GitHub Actions 的 OIDC issuer），當管線執行時，CI 平台簽發一個帶有可驗證 claim 的 token（描述「這是哪個 repo、哪個 branch、哪個 workflow 在跑」），雲端用這個 token 換出一段臨時憑證。沒有任何長期 secret 需要被儲存在 CI 設定裡。

trust policy 的收斂

關鍵設計在 role 的 trust policy 上 — 它規定「哪個外部身分被允許假扮成這個 role」。trust policy 要用 token 的 claim 把假扮條件收到最緊。

 1# OIDC trust policy：只允許特定 repo 的 main branch 假扮此 role
 2data "aws_iam_policy_document" "ci_trust" {
 3  statement {
 4    actions = ["sts:AssumeRoleWithWebIdentity"]
 5
 6    principals {
 7      type        = "Federated"
 8      identifiers = [aws_iam_openid_connect_provider.github.arn]
 9    }
10
11    condition {
12      test     = "StringEquals"
13      variable = "token.actions.githubusercontent.com:aud"
14      values   = ["sts.amazonaws.com"]
15    }
16
17    condition {
18      test     = "StringLike"
19      variable = "token.actions.githubusercontent.com:sub"
20      values   = ["repo:my-org/my-app:ref:refs/heads/main"]
21    }
22  }
23}

每個 condition 各守一段邊界。aud 的 StringEquals 確認 token 是發給 AWS STS 的（防止用錯 audience 的 token 闖入）。sub 的 StringLike 把假扮限定在特定 repo 的 main branch — 設成 repo:my-org/* 等於讓組織內任何 repo 的任何 branch 都能假扮這個 role，這是常見的設定陷阱。

收斂 trust policy 的判讀問法是：「如果 my-org 底下某個公開 fork 跑了一個惡意 workflow，它能不能假扮這個 role？」如果答案是能，sub 條件就太鬆了。

分離 plan 與 apply 的 role

進一步的收斂是替 plan 和 apply 分別建立 role。plan 只需要唯讀存取（讀 state、讀雲端現況），apply 需要寫入權限。把兩者分成獨立 role，讓 PR 階段的 CI 用唯讀 role 跑 plan、合併後才用寫入 role 跑 apply。任何拿到 plan role 的 token 無法修改基礎設施。

 1# plan role：只需讀取 state 與雲端現況
 2resource "aws_iam_role" "ci_plan" {
 3  name               = "infra-ci-plan"
 4  assume_role_policy = data.aws_iam_policy_document.ci_trust.json
 5}
 6
 7resource "aws_iam_role_policy_attachment" "ci_plan_read" {
 8  role       = aws_iam_role.ci_plan.name
 9  policy_arn = "arn:aws:iam::aws:policy/ReadOnlyAccess"
10}
11
12# apply role：需要寫入權限，trust policy 限定只有 main branch
13resource "aws_iam_role" "ci_apply" {
14  name               = "infra-ci-apply"
15  assume_role_policy = data.aws_iam_policy_document.ci_trust_main_only.json
16}

這一章把 role 與 trust policy 設計好，OIDC 的實際回報要到模組七：infra 走 PR 流程建管線時才兌現 — 屆時管線用這裡定義好的 role 取得短期權限執行 plan 與 apply，CI 環境裡不需要存任何 access key。

權限邊界設計

權限邊界是把不同類型的身分與不同環境之間的權限刻意隔開，讓任何一個身分被攻破時，爆炸半徑都被限制在它本職的範圍內。邊界設計有兩條軸線需要分別處理：人 vs 機器，以及環境之間。

人 vs 機器

兩者的存取模式根本不同，混在同一個身分上會同時喪失兩邊的保護。

人類身分需要互動式登入、應該強制 MFA、權限隨職責變動，且通常透過 SSO 集中管理。機器身分（CI runner、ECS task、Lambda function）需要的是程式化、無人值守的存取，應該用 role 假扮取得短期憑證，永遠不該配長期 key。

機器身分還要再依「跑在哪裡」分兩類。跑在雲上的 workload（EC2 instance、ECS task、Lambda）由平台直接把 role 綁在執行環境上 — AWS 用 instance profile 把 role 掛在 EC2、用 task role 掛在 ECS task，workload 從實例 metadata 端點自動取得輪替的短期憑證。跑在雲外的 CI/CD（GitHub Actions、GitLab CI）拿不到實例 metadata，需要前面那套 OIDC 信任關係換憑證。

一個常見陷阱是工程師用自己的個人 key 跑自動化腳本 — 這把人的廣泛權限直接送進了無人值守的執行環境，MFA 保護形同虛設（API 呼叫不需要 MFA challenge），權限範圍比任何 CI role 都大。

環境之間

環境之間的邊界，目的是讓 production 的權限與 staging、dev 完全不交叉。驗證邊界的方式是用 dev 環境的 CI role 嘗試列出或刪除 production 的資源——能做到，就代表邊界沒有建立。

帳號級護欄：SCP

Organizations 把環境拆成獨立帳號，再用 SCP（Service Control Policy）對整個帳號或組織單位設定權限天花板，連帳號內的管理員都越不過去。SCP 是 deny-based 的頂層限制 — 它不授予任何權限，只限制「即使有人給了權限也不准做」。

 1{
 2  "Version": "2012-10-17",
 3  "Statement": [
 4    {
 5      "Sid": "DenyLeaveOrg",
 6      "Effect": "Deny",
 7      "Action": ["organizations:LeaveOrganization"],
 8      "Resource": "*"
 9    },
10    {
11      "Sid": "DenyDisableCloudTrail",
12      "Effect": "Deny",
13      "Action": [
14        "cloudtrail:StopLogging",
15        "cloudtrail:DeleteTrail"
16      ],
17      "Resource": "*"
18    }
19  ]
20}

這份 SCP 掛在整個組織底下的所有帳號上，確保任何帳號都不能關閉稽核日誌或退出組織 — 即使該帳號裡有人持有 AdministratorAccess。SCP 的定位是組織層的不可踰越底線。

Role 級護欄：Permissions Boundary

Permissions Boundary 是掛在單一 role 上的權限上限。它跟 SCP 的差別在粒度：SCP 管整個帳號，Permissions Boundary 管單一身分。即使有人後來給一個 role 貼了過寬的 policy，Boundary 也會擋住超出上限的部分。

 1# Permissions Boundary：CI role 最多只能操作特定服務
 2resource "aws_iam_policy" "ci_boundary" {
 3  name = "ci-boundary-prod"
 4  policy = jsonencode({
 5    Version = "2012-10-17"
 6    Statement = [
 7      {
 8        Effect   = "Allow"
 9        Action   = ["ecs:*", "ecr:*", "s3:*", "logs:*"]
10        Resource = "*"
11      },
12      {
13        Effect   = "Deny"
14        Action   = ["iam:*", "organizations:*", "account:*"]
15        Resource = "*"
16      }
17    ]
18  })
19}
20
21resource "aws_iam_role" "ci_apply" {
22  name                 = "infra-ci-apply"
23  assume_role_policy   = data.aws_iam_policy_document.ci_trust.json
24  permissions_boundary = aws_iam_policy.ci_boundary.arn
25}

SCP 與 Permissions Boundary 疊起來的效果是：SCP 在帳號層鎖住最危險的操作（關日誌、退組織），Boundary 在 role 層限制單一身分最多能做什麼，permissions policy 在這兩層天花板之內授予實際需要的權限。三者各管一層，缺一層就少一道屏障。

身分控制面本身的韌性在兩個案例中被檢驗。Azure AD 2021 事件中，身分服務的控制面故障導致所有依賴身份驗證的服務同時受影響，事故處理需要在身份恢復與服務降級策略之間排優先序（見 Azure AD：Identity Control-plane 事件）。Microsoft Storm-0558 事件則顯示簽章金鑰一旦失守，token 驗證的信任鏈會跨租戶失效，修復不只是修補漏洞、而是重建整條 key lifecycle 與 issuer 驗證流程（見 Microsoft：Storm-0558 簽章金鑰事件）。這兩個案例揭露的是：權限邊界只管「某個身分能做什麼」，但身分系統本身的控制面如果失效，所有建立在它之上的邊界都跟著失效。

環境隔離的更完整實作（帳號結構、模組化參數）會在模組四：環境分離與模組化展開。

身分層 vs 應用層 secret 的邊界

這一章談的是身分與憑證 — 誰是誰、怎麼證明、能動什麼。憑證背後引用的應用層 secret（資料庫密碼、第三方 API key）怎麼安全儲存與注入，屬於模組八：治理好習慣的 secret management 範圍。兩者的交集是：身分層決定「誰能讀到 secret store」，secret 層決定「secret 怎麼存與輪替」。把 IAM role 的 policy 收到只能讀取該服務路徑下的 secret（如 prod/payments/*），是同時落實最小權限與 secret 隔離的結合點。

身分與憑證的地基備妥後，下一步是劃清服務之間的網路邊界——這正是模組三：網路地基的範圍。

跨分類引用

• → 模組負一：還沒有 infra 的環境：長期 key 盤點與護欄
• → 模組三：網路地基：身分備妥後，劃清服務之間的網路邊界
• → 模組四：環境分離與模組化：環境之間的帳號結構與隔離強度
• → 模組七：infra 走 PR 流程：CI/CD 管線用 OIDC 取得短期權限
• → 模組八：治理好習慣：應用層 secret 的儲存與引用
• → backend 模組七：資安與資料保護：Secret Management 與憑證管理交集
• → Access Key 輪替手冊：key 盤點與輪替的操作步驟
• → OIDC Trust Policy 設定指南：GitHub Actions OIDC 的 step-by-step 設定

單帳號 vs 多帳號：什麼時候該切

單帳號在早期是合理的起點 — 資源少、人少、管理成本低。帳號邊界帶來的隔離收益要跟它的管理成本比較：每多一個帳號就多一份 CloudTrail、多一組 IAM 基線、多一個需要管理的 state backend。

三個訊號出現時，單帳號的邊際風險開始超過多帳號的管理成本：

第一，production 和 dev 的資源開始互相影響。一個 dev 環境的壓力測試把帳號的 EC2 instance quota 吃滿，production 的 auto-scaling 因為拿不到新 instance 而失敗 — 這個故障跟程式碼品質無關，純粹是兩個環境共用同一組配額。帳號分開後，dev 吃滿自己的 quota 不會碰到 production。

第二，權限邊界用 IAM 已經管不住。一個工程師的 IAM policy 限制他只能操作 env=dev 的資源，但他手滑用了一個沒有 tag 條件的 policy、或者某個 IAM role 的 trust policy 太寬，他就能碰到 production 資源。帳號邊界是比 IAM policy 更硬的護欄 — 即使 IAM 設定出錯，帳號邊界本身就是物理隔離。

第三，合規或稽核要求明確區分環境。SOC 2 或金融監管可能要求 production 環境有獨立的存取紀錄和變更審計，與開發環境完全分離。同帳號裡做這件事要靠大量的 IAM 條件和 CloudTrail filter，跨帳號則天然滿足。

OU 結構：帳號怎麼分群

AWS Organizations 用 Organizational Unit（OU）把帳號分群，OU 是 SCP 的掛載點 — 一條 SCP 掛在 OU 上，底下所有帳號都受約束。OU 的設計決定了護欄的作用範圍。

常見的 OU 拓撲有四層：

環境怎麼對應到帳號，跟模組四的環境分離是同一個問題的不同層次 — 模組四用目錄和 state 分離環境的 IaC，這裡用帳號分離環境的雲端資源。兩者可以疊加：每個帳號裡的 IaC 仍然用獨立目錄和 state 管理。

OU 結構的設計原則是「按信任等級分群、按職責隔離」。Prod 跟 NonProd 分開是因為信任等級不同（prod 的 SCP 更嚴格）。Security 獨立是因為它的職責是「監控其他所有帳號」— 如果 security 帳號被攻破，攻擊者能修改稽核日誌來掩蓋行蹤，所以它的存取權限要收到最小。

一個常見的錯誤是把 OU 當成組織架構的映射（按部門分 OU）。OU 的分群依據是安全邊界和 SCP 策略，不是彙報線。兩個部門如果需要相同的 SCP，它們的帳號應該在同一個 OU 底下；一個部門如果有 prod 和 dev 環境，它們應該在不同 OU 底下。

SCP：連管理員都越不過的護欄

Service Control Policy（SCP）是掛在 OU 或帳號上的權限天花板。它跟 IAM policy 的差別是層級：IAM policy 控制「這個身分能做什麼」，SCP 控制「這個帳號裡的任何身分最多能做什麼」。即使帳號內的 root user 或 AdministratorAccess role，也受 SCP 約束。

SCP 的設計策略以 deny-list 為主 — 預設允許所有動作，用 SCP 明確禁止少數高風險操作。相比 allow-list（預設禁止、逐一開放），deny-list 的管理成本低得多，因為 AWS 的 service 和 action 數量龐大，逐一列舉允許清單容易漏、也容易在新服務上線時擋住正常使用。

三條適合從第一天就掛上去的 SCP：

禁止關閉 CloudTrail

 1{
 2  "Version": "2012-10-17",
 3  "Statement": [{
 4    "Sid": "DenyCloudTrailDisable",
 5    "Effect": "Deny",
 6    "Action": [
 7      "cloudtrail:StopLogging",
 8      "cloudtrail:DeleteTrail",
 9      "cloudtrail:UpdateTrail"
10    ],
11    "Resource": "*"
12  }]
13}

CloudTrail 是事後追溯「誰做了什麼」的唯一來源。攻擊者入侵帳號後的第一步往往是關掉稽核日誌來掩蓋行蹤，用 SCP 禁止這個動作，讓日誌在帳號層級不可關閉。

禁止離開指定 region

 1{
 2  "Version": "2012-10-17",
 3  "Statement": [{
 4    "Sid": "DenyOutsideRegion",
 5    "Effect": "Deny",
 6    "NotAction": [
 7      "iam:*",
 8      "sts:*",
 9      "organizations:*",
10      "support:*"
11    ],
12    "Resource": "*",
13    "Condition": {
14      "StringNotEquals": {
15        "aws:RequestedRegion": ["ap-northeast-1", "us-east-1"]
16      }
17    }
18  }]
19}

限制資源只能建在指定 region，避免有人在沒人注意的 region（如 af-south-1）開資源 — 不管是誤操作還是攻擊者利用。NotAction 裡排除 IAM 和 STS 等全域服務，因為它們不分 region。us-east-1 通常要保留，因為 CloudFront、ACM（global cert）等服務的 API 端點在 us-east-1。

禁止刪除 VPC Flow Logs

1{
2  "Version": "2012-10-17",
3  "Statement": [{
4    "Sid": "DenyDeleteFlowLogs",
5    "Effect": "Deny",
6    "Action": "ec2:DeleteFlowLogs",
7    "Resource": "*"
8  }]
9}

VPC Flow Logs 記錄網路層的流量軌跡，是安全事件排查的關鍵資料。跟 CloudTrail 的邏輯一樣 — 稽核資料不允許被帳號內的操作者刪除。

SCP 的繼承模型

SCP 沿著 OU 樹向下繼承：掛在 Root OU 的 SCP 對所有帳號生效，掛在子 OU 的 SCP 只對該 OU 底下的帳號生效。多層 SCP 的效果是交集 — 父 OU 禁止的動作，子 OU 無法用 SCP 重新允許。這個交集模型讓安全團隊能在頂層設「絕對底線」，各子 OU 只能在底線之內進一步收斂、不能放寬。

把 SCP 用 Terraform 管理：

 1resource "aws_organizations_policy" "deny_cloudtrail_disable" {
 2  name        = "deny-cloudtrail-disable"
 3  description = "Prevent anyone from stopping or deleting CloudTrail"
 4  type        = "SERVICE_CONTROL_POLICY"
 5  content     = file("policies/deny-cloudtrail-disable.json")
 6}
 7
 8resource "aws_organizations_policy_attachment" "root_deny_cloudtrail" {
 9  policy_id = aws_organizations_policy.deny_cloudtrail_disable.id
10  target_id = aws_organizations_organization.main.roots[0].id
11}

SCP 的 JSON 存在 repo 的 policies/ 目錄，變更走 PR review，讓護欄本身也在版本控制與審查流程裡。

控制面 token 的治理是 SCP 護欄之外需要同步處理的議題。Cloudflare 2023 事件中，控制面 token 的生命週期與最小權限沒有對齊，機器憑證形成跨服務的高權限風險（見 Cloudflare：Control-plane Token 事件）。Okta 2023 事件則顯示身份治理若只覆蓋生產系統而忽略支援工具鏈，支援系統的 session 和 token 會成為跨租戶的風險放大點（見 Okta：Support System 事件）。兩個案例的共同教訓是：SCP 管的是 AWS API 層的動作上限，但 token / session 這類應用層的機器憑證需要獨立的 lifecycle 治理。

帳號工廠：每個新帳號自帶安全基線

跨帳號策略（帳號數量、OU 結構、SCP 規則）屬於影響全組織的架構決策，建議在實施前取得技術主管或 CTO 的對齊。SCP 一旦套用到 OU，該 OU 下所有帳號立即受影響，回退需要修改 SCP 或移動帳號到不同 OU。

手動建帳號的問題跟手動建資源一樣 — 每次都靠人記得「開完帳號後要開 CloudTrail、要刪預設 VPC、要設基線 IAM role」。帳號工廠（Account Factory）把這些步驟自動化成一個可重複的流程：建一個帳號、自動套用安全基線、自動加進正確的 OU。

AWS Control Tower 是 AWS 提供的帳號工廠實作，它包裝了 Organizations、SCP、Config Rules 和 CloudFormation StackSet，提供一個「建帳號 → 自動配置」的流水線。它的好處是一鍵啟用、內建一組 AWS 建議的護欄；代價是它對 OU 結構和 SCP 有自己的意見，跟團隊已有的設計可能衝突，而且它用 CloudFormation StackSet 做基線配置，跟 Terraform 管理的資源需要劃清邊界。

不用 Control Tower 時，帳號工廠可以用 Terraform + 腳本自建。核心是一個 module 接受帳號名稱和 OU 作為參數，產出：帳號建立、CloudTrail trail、預設 VPC 刪除、基線 IAM role（讓管理帳號能 assume 進來做維護）、Config recorder 啟用。

每個新帳號該自帶的安全基線至少包含：

• CloudTrail 開啟並寫到集中的 Log Archive 帳號
• 預設 VPC 刪除（預設 VPC 的 security group 全通、CIDR 固定且跨帳號重複，留著是隱患）
• 基線 IAM role 讓管理帳號能 assume 進來
• Config recorder 啟用（記錄資源設定變更歷史）
• 掛上所屬 OU 的 SCP

導入時程參考：初次設定 Organizations + OU 結構 + day-1 SCP 約需 2-3 天；之後每開一個新帳號（含基線配置）約需 2-4 小時。

跨帳號存取：role assumption

多帳號架構裡，人或自動化需要在不同帳號之間切換操作。跨帳號存取用 IAM role 的 trust policy 實現 — 目標帳號建一個 role，trust policy 允許來源帳號的特定身分 assume 這個 role。

AWS Organizations 在建子帳號時會自動建一個 OrganizationAccountAccessRole，讓管理帳號的 admin 能 assume 進去。這個 role 的權限是 AdministratorAccess — 它的用途是初始設定和緊急存取，日常操作不該用它。日常的跨帳號存取應該建立職責專用的 role：部署用的 role 只有部署相關權限、唯讀稽核用的 role 只有 read 權限。

 1resource "aws_iam_role" "deploy_from_cicd" {
 2  name = "deploy-from-cicd-account"
 3
 4  assume_role_policy = jsonencode({
 5    Version = "2012-10-17"
 6    Statement = [{
 7      Effect    = "Allow"
 8      Principal = { AWS = "arn:aws:iam::111111111111:role/cicd-runner" }
 9      Action    = "sts:AssumeRole"
10      Condition = {
11        StringEquals = { "sts:ExternalId" = "deploy-prod-2026" }
12      }
13    }]
14  })
15}

ExternalId 是防止 confused deputy 攻擊的機制 — 如果 trust policy 只用帳號 ID 驗證，任何能在來源帳號建 role 的人都能 assume 目標 role。加上 ExternalId 讓 assumption 多一個只有雙方知道的驗證值。

跨帳號存取的設計與模組二的 OIDC 短期憑證互補 — OIDC 解決「雲外到雲內」的身分聯合（CI/CD → AWS），role assumption 解決「雲內帳號之間」的身分切換。

帳單整合

Organizations 的附帶收益是合併帳單（Consolidated Billing）。所有子帳號的用量合併到管理帳號的帳單裡，一方面簡化付款流程（一張帳單而非多張），另一方面可以享受跨帳號的用量折扣 — 例如 S3 的定價階梯是看總用量，三個帳號各用 1TB 分開計費跟合併成 3TB 計費，後者的單位價格更低。

合併帳單跟成本歸屬的 tagging 互補。合併帳單讓所有費用匯到一張帳單，tagging 讓這張帳單能拆到各團隊和用途 — 這兩件事在模組八的成本可見性展開。帳號邊界本身也是一層成本隔離：每個帳號的用量可以獨立查看，讓「這個帳號這個月花了多少」變成自動可查、不需要依賴 tag。

跨分類引用

• → 身分與憑證地基：IAM role / policy / OIDC 是帳號內的身分控制，本篇是帳號間的隔離
• → 環境分離與模組化：目錄與 state 分離環境的 IaC，帳號分離是雲端資源層的對應
• → 成本可見性：合併帳單 + tagging 的成本歸屬
• → infra 走 PR 流程：SCP 的 JSON 存 repo、變更走 PR review

權限分級：admin / operator / viewer

團隊成員的日常操作權限用三級來劃分，每一級對應不同的操作範圍與風險。分級的依據是「這個角色的日常工作需要碰到什麼層級的資源」，不是職稱或年資。

Admin

Admin 能修改 IAM policy、網路拓撲、帳號層級設定（Organizations、SCP、billing）。這是影響範圍最大的一級——一條 SCP 寫錯可以鎖死整個帳號的操作，一條 IAM policy 開太寬可以讓任何角色取得不該有的權限。

持有 admin 權限的人數應該收斂到最少：通常是平台團隊的 1-2 人加上一個 break-glass 備援角色。Admin 權限不應該是某個人的「日常身分」——即使是平台工程師，日常操作也用 operator 等級，只有在需要改 IAM 或帳號設定時才 assume 到 admin role。

 1# Admin role 的信任政策：只允許特定 IAM user assume
 2data "aws_iam_policy_document" "admin_trust" {
 3  statement {
 4    actions = ["sts:AssumeRole"]
 5    principals {
 6      type        = "AWS"
 7      identifiers = [
 8        "arn:aws:iam::123456789012:user/platform-lead",
 9        "arn:aws:iam::123456789012:user/platform-backup",
10      ]
11    }
12    condition {
13      test     = "Bool"
14      variable = "aws:MultiFactorAuthPresent"
15      values   = ["true"]
16    }
17  }
18}
19
20resource "aws_iam_role" "admin" {
21  name               = "infra-admin"
22  assume_role_policy = data.aws_iam_policy_document.admin_trust.json
23  max_session_duration = 3600  # 1 小時後自動失效
24}

max_session_duration 限制 assume 後的有效時間。Admin session 設 1 小時是讓操作者完成當次任務後權限自動回收，不需要手動登出。MFA 條件確保即使帳號密碼外洩，沒有第二因素也無法提權。

Operator

Operator 能部署服務、修改應用層資源（ECS task、RDS parameter group、S3 lifecycle）、查看與操作日常維運所需的一切。多數工程師的日常身分落在這一級。

Operator 的 policy 用 resource scope 限制它碰不到 IAM 和帳號層級設定——能改 ECS service 但不能改 ECS service 用的 IAM role，能改 RDS 參數但不能改 RDS 的 subnet group。這個邊界讓 operator 的操作失誤影響範圍停在服務層，不會擴散到地基層。

 1data "aws_iam_policy_document" "operator" {
 2  # 允許操作應用層資源
 3  statement {
 4    actions = [
 5      "ecs:UpdateService", "ecs:DescribeServices",
 6      "rds:ModifyDBInstance", "rds:DescribeDBInstances",
 7      "s3:GetObject", "s3:PutObject",
 8      "logs:GetLogEvents", "logs:FilterLogEvents",
 9    ]
10    resources = ["*"]
11  }
12
13  # 明確拒絕碰 IAM 和帳號設定
14  statement {
15    effect = "Deny"
16    actions = [
17      "iam:*",
18      "organizations:*",
19      "account:*",
20    ]
21    resources = ["*"]
22  }
23}

Deny 語句確保即使未來有人不小心把過寬的 managed policy attach 到 operator role，IAM 和帳號操作仍然被擋。Deny 在 IAM 評估中優先於 Allow。

Viewer

Viewer 能讀取 Console、查 log、看 metric dashboard，但不能修改任何資源。適合的角色包括：值班但不需要改設定的 on-call、需要查 log 排查問題的 support 團隊、需要看資源狀態的管理層。

Viewer 用 AWS 的 managed policy ReadOnlyAccess 作為基線，再根據需要排除敏感資料的讀取（例如 Secrets Manager 的 GetSecretValue）。

三級的對應關係：

導入時程參考：三級權限的 IAM role 與 policy 建立約需 1-2 天，包含 trust policy 設定與初次分配。後續的權限變更走版本控制的 PR 流程，讓每次 policy 調整都有提案、審查與歷史紀錄（見infra 走 PR 流程）。

臨時提權（break-glass）

Operator 在日常工作中偶爾需要 admin 層級的操作——排查一個涉及 IAM 的事故、緊急修改一條 security group 規則、回應安全事件。常態性地把 admin 權限開給所有 operator 會讓三級分級失效，但每次都等 admin 角色的人上線又太慢。Break-glass 流程處理的就是這個中間地帶。

機制

Break-glass 的實作是一個平時不被 assume 的 admin role，加上一套提權紀錄。Operator 在需要時 assume 這個 role，取得一段時效有限的 admin session。這個 assume 動作會在 CloudTrail 留下紀錄（誰、什麼時候、session 多長），事後可稽核。

1resource "aws_iam_role" "break_glass" {
2  name                 = "infra-break-glass"
3  assume_role_policy   = data.aws_iam_policy_document.break_glass_trust.json
4  max_session_duration = 3600
5
6  tags = { Purpose = "emergency-escalation" }
7}

如果團隊有 ChatOps 或 ticketing 系統，把 break-glass 的觸發綁進去可以增加一層人為確認：operator 在 Slack 或 ticket 裡申請提權、另一個人核可、系統開放 assume。這層確認的目的是在事後稽核時留下一條清楚的「誰授權了這次提權」紀錄，而非阻止操作本身。

事後回顧

每一次 break-glass 使用都應該進入事後回顧：為什麼需要提權？這個操作能不能改寫成 operator 層級的權限就能完成？如果某類操作反覆觸發 break-glass，代表 operator 的權限邊界需要調整——把那類操作從 admin 降到 operator，而不是讓 break-glass 變成常態。

回顧的輸出是權限邊界的校準，不是對操作者的檢討。

定期 access review

權限分配不是一次性的設定。人會換組、離職、從 contractor 轉正職、從開發角色轉管理角色，每一次角色變動都可能讓既有的權限配置過期。定期 review 的責任是找出「權限比當前角色需要的更寬」的身分，把它們收斂回來。

節奏與方法

每季做一次 access review 是多數團隊能維持的最小節奏。Review 的步驟：

1. 拉出所有 IAM user 和 role 的清單，標注每個身分目前的分級（admin / operator / viewer）
2. 比對每個身分的實際角色——這個人現在還在做需要 operator 權限的工作嗎？
3. 用 IAM Access Analyzer 檢查哪些權限在過去 90 天沒被使用過——沒用到的權限是收斂候選
4. 特別檢查 break-glass 的使用紀錄——有沒有人的 break-glass 使用頻率高到代表他的基線權限該調整

1# 產出 credential report，列出所有 user 的 key 建立時間與使用時間
2aws iam generate-credential-report
3aws iam get-credential-report --output text --query Content | base64 -d | head -20
4
5# 查 Access Analyzer 的 finding（哪些權限可收斂）
6aws accessanalyzer list-findings --analyzer-arn <analyzer-arn> \
7  --filter '{"status": {"eq": ["ACTIVE"]}}'

管理層報告

Access review 的結果適合用兩個數字向管理層報告：覆蓋率（已 review 的身分數 / 總身分數）與異常數（權限過寬或長期未使用的身分數）。異常數的趨勢比單次數字更有意義——持續上升代表新人 onboarding 時的權限配置流程有缺口，持續下降代表 review 在發揮作用。

導入時程參考：第一次 access review 約需半天到一天（盤點 + 比對 + 收斂），後續每季約需 2-4 小時。

職務交接與離職處理

一個人離開團隊時，他持有的所有存取路徑都需要被回收。手動建立的存取路徑越多，離職處理越容易遺漏。

離職 checklist

權限設計越集中在 role-based（用 IAM group 或 SSO permission set），離職處理越簡單——停用 SSO 帳號就自動切斷所有透過 SSO 取得的 role。反過來，如果有大量手動 attach 的 policy 或直接寫在 trust policy 裡的 user ARN，離職時要逐一找出並移除，容易遺漏。

離職後的 credential rotation 有一個常被忽略的風險：輪替範圍沒有按作用域分批。一個反例是多個服務共用同一把 secret，輪替時切新憑證的服務跟還只認舊憑證的服務之間出現認證窗口不一致，導致跨系統連鎖中斷。穩定的做法是先分域隔離受影響服務、恢復雙憑證窗口、再逐批收斂（見 反例：憑證輪替未分 Scope）。

交接的可執行性

交接的成本取決於知識有多少沉澱在程式碼裡、有多少留在個人腦中。如果環境的建立方式是一份 IaC、變更方式是 PR 歷史，新接手的人讀 code 跟 PR 描述就能重建脈絡。如果關鍵操作（某台資料庫的特殊 parameter、某條 security group 規則的理由）只存在離職者的記憶裡，交接窗口一過就永久遺失。

可操作的檢驗：問「如果這個人下週離職，團隊能不能只靠讀 repo 就安全地操作他負責的環境？」答案是否定的部分，就是交接的優先補強項——優先把它們寫進 IaC 或 PR 描述，而不是寫進交接文件（交接文件會過期，IaC 跟著環境一起演進）。

這個議題在知識共享優於個人英雄主義有組織層面的展開。

Contractor 與外部 vendor 存取

外部人員（contractor、顧問、SaaS vendor 的技術支援）需要存取雲端環境時，原則是給最小範圍、設明確時限、留完整紀錄。

範圍限制

外部人員的 role 用 Permissions Boundary 設定權限天花板，確保即使有人誤 attach 了過寬的 policy，操作範圍也不超過 boundary 允許的上限。Scope 到具體的資源 ARN（某個 S3 bucket、某台 RDS instance），而非帳號級別的 wildcard。

如果團隊已經有跨帳號策略，把外部人員的 workload 放在獨立帳號或 sandbox OU 裡，用 SCP 限制該帳號能操作的服務類型，是比 role 級別限制更強的隔離。

時限控制

外部存取的 IAM user 或 SSO 帳號在建立時就設定到期日。多數雲端平台支援 session duration 限制（role 的 max_session_duration）和帳號層級的停用排程。合約結束日應該對應到存取到期日——這個對應關係寫進 IaC（用 tag 標注到期日）或團隊的 access review checklist，避免合約結束後存取仍然開著。

稽核紀錄

外部人員的操作需要比內部人員更嚴格的稽核。CloudTrail 預設記錄所有 API 呼叫，但 review 的頻率要提高——外部人員的操作紀錄每週抽查，而非等到季度 access review 才回頭看。查的是：有沒有存取超出約定範圍的資源？有沒有在非工作時間操作？有沒有大量的 read 操作指向敏感資料？

這些紀錄同時也是合約管理的依據——如果外部 vendor 的技術支援存取了超出約定範圍的資源，紀錄是釐清責任的事實基礎。

跨分類引用

• → 身分與憑證地基：IAM role / policy / OIDC 的技術機制
• → 跨帳號策略：用 OU 和 SCP 在帳號層級隔離外部人員
• → 治理好習慣：tagging 標注存取到期日、secrets 不進 code
• → 怎麼把 infra 推動起來：知識共享與交接的組織面

盤點：帳號裡有哪些 key

第一步是拿到帳號內所有 IAM user 的 access key 清單。AWS 的 credential report 是這個問題的標準資料來源，它列出每個 user 的 key 狀態、建立時間與最後使用時間。

1aws iam generate-credential-report
2aws iam get-credential-report \
3  --query 'Content' --output text | base64 -d > credential-report.csv

產出的 CSV 包含每個 IAM user 的兩把 key（access_key_1、access_key_2）各自的狀態。關注的欄位：

用 csvkit 或試算表打開這份報告，按 access_key_1_last_rotated 排序，最舊的 key 排最前面。超過 90 天未輪替的 key 列為第一批處理對象。

以下腳本使用 gawk 的 systime() 函式。如果系統的 awk 是 mawk（Ubuntu 預設），改用 gawk 或用 date 指令替代時間計算。

 1# 快速列出所有啟用中、超過 90 天的 key
 2aws iam list-users --query 'Users[].UserName' --output text | tr '\t' '\n' | while read user; do
 3  aws iam list-access-keys --user-name "$user" \
 4    --query "AccessKeyMetadata[?Status=='Active'].[UserName,AccessKeyId,CreateDate]" \
 5    --output text
 6done | awk -F'\t' '{
 7  cmd = "date -d \"" $3 "\" +%s 2>/dev/null || date -jf \"%Y-%m-%dT%H:%M:%S+00:00\" \"" $3 "\" +%s"
 8  cmd | getline created; close(cmd)
 9  age = (systime() - created) / 86400
10  if (age > 90) printf "%s\t%s\t%.0f days\n", $1, $2, age
11}'

識別每把 key 的用途

知道 key 存在之後，下一個問題是「這把 key 用在哪裡」。credential report 只告訴你 key 最後被用來呼叫什麼 service（access_key_1_last_used_service），但不告訴你它被存放在哪裡。

用途識別需要交叉比對多個來源：

對每把要輪替的 key，在以上位置逐一確認。找不到用途的 key 可以先停用觀察（而非直接刪除），停用後如果有服務壞了就知道它用在哪裡。

輪替步驟：五步流程

輪替一把 key 的標準流程分五步，順序不能跳：

第一步：建立新 key

1aws iam create-access-key --user-name deploy-bot

輸出會包含新的 AccessKeyId 和 SecretAccessKey。SecretAccessKey 只在這一刻顯示一次，存進密碼管理器或 Secrets Manager，不要貼在 Slack 或 email 裡。

一個 IAM user 最多同時有兩把 key。如果已經有兩把，需要先刪除一把不用的才能建新的。

第二步：更新所有消費者

把新 key 部署到上一節識別出的所有存放位置。CI 變數、Lambda 環境變數、SSM Parameter Store、開發者的 ~/.aws/credentials 都要同步更新。

每更新一個消費者就做一次功能驗證——CI 跑一次 pipeline、Lambda 觸發一次、開發者跑一次 aws sts get-caller-identity 確認新 key 能用。

第三步：驗證新 key 生效

所有消費者更新完後，等待一個完整的業務週期（至少 24 小時），確認沒有任何服務還在用舊 key。檢查方式是看舊 key 的 LastUsedDate 有沒有在更新之後還被使用：

1aws iam get-access-key-last-used --access-key-id AKIAOLD12345

如果 LastUsedDate 在你更新消費者之後仍有新的使用紀錄，代表有漏網的消費者還在用舊 key。

第四步：停用舊 key

確認無殘留使用後，停用（不是刪除）舊 key：

1aws iam update-access-key \
2  --user-name deploy-bot \
3  --access-key-id AKIAOLD12345 \
4  --status Inactive

停用是安全的中間狀態——用到這把 key 的服務會開始報 InvalidClientTokenId 錯誤，但 key 還在、可以隨時重新啟用。如果停用後有意料之外的服務壞了，重新啟用就能立刻恢復。

第五步：寬限期後刪除

停用後保持 7-14 天的寬限期。這段時間是「如果有漏掉的消費者」的安全網。寬限期內無異常，刪除：

1aws iam delete-access-key \
2  --user-name deploy-bot \
3  --access-key-id AKIAOLD12345

刪除後不可回復。如果有服務還在用這把 key，只能建一把新 key 然後去更新那個服務。

自動化輪替：Secrets Manager

手動輪替的瓶頸在「找到所有消費者」這一步。如果 key 的消費者都從 Secrets Manager 讀取（而非各自存一份副本），輪替就簡化成「在 Secrets Manager 裡更新值」——所有消費者下次讀取時自動拿到新 key。

Secrets Manager 支援自動輪替：設定一個 Lambda function 作為 rotation function，它負責建新 key → 更新 secret value → 停用舊 key 的全流程。

 1resource "aws_secretsmanager_secret" "deploy_key" {
 2  name = "prod/deploy-bot/access-key"
 3}
 4
 5resource "aws_secretsmanager_secret_rotation" "deploy_key" {
 6  secret_id           = aws_secretsmanager_secret.deploy_key.id
 7  rotation_lambda_arn = aws_lambda_function.key_rotator.arn
 8
 9  rotation_rules {
10    automatically_after_days = 90
11  }
12}

自動輪替的前提是所有消費者都改成從 Secrets Manager 讀 key，而非從環境變數或設定檔。這個前提本身就是一次 migration——跟手動輪替的固定成本（盤點 + 更新 + 驗證）相比，migration 的一次性成本更高，但之後的每次輪替接近零成本。

判斷該不該投入自動化的依據是 key 的數量和輪替頻率。3 把 key、每季輪替一次，手動流程 2-3 小時可以完成，自動化的 ROI 不高。10 把以上、或合規要求 30 天輪替，手動已經吃掉固定的工程師時間，自動化的投入才有回報。

Key age 監控

輪替做完不代表可以不管——如果沒有監控，三個月後又會回到「不知道有幾把超齡的 key」的狀態。

最低成本的監控是一條定期跑的 check，掃描所有 key 的年齡並在超過閾值時告警：

1# 列出所有超過 90 天的 active key（用 AWS Config 規則更可靠）
2aws configservice put-config-rule --config-rule '{
3  "ConfigRuleName": "access-keys-rotated",
4  "Source": {
5    "Owner": "AWS",
6    "SourceIdentifier": "ACCESS_KEYS_ROTATED"
7  },
8  "InputParameters": "{\"maxAccessKeyAge\":\"90\"}"
9}'

AWS Config 的 ACCESS_KEYS_ROTATED managed rule 會持續掃描所有 IAM user 的 key age，超過設定天數的標記為 non-compliant。把 Config 的 non-compliant 事件接到 SNS → Slack 或 email，就有了持續的 key 超齡告警。

Prowler 也提供 key age 檢查（prowler aws --checks access_key_1_rotated），適合當一次性掃描工具。Config rule 適合持續監控。

管理層報告可以用 Config 的 compliance dashboard：compliant key 數 / 總 key 數 = key rotation 覆蓋率，這個百分比適合放進月報。

IAM Access Analyzer 的 unused access 功能（需啟用 analyzer）可以持續掃描帳號內未使用的 key 和 permission，跟 Config rule 互補——Config 看 key age，Access Analyzer 看 key 是否被使用。兩者搭配可以同時回答「這把 key 多久沒輪替」和「這把 key 有沒有在用」。

跨分類引用

• → 身分與憑證地基：access key 風險的系統性分析、OIDC 作為長期 key 的替代方案
• → 團隊權限分級與存取管理：離職時的 key 撤銷流程
• → 治理好習慣：secret 的儲存與引用紀律

本篇以 GitHub Actions 為主，其他平台替換 issuer URL 和 sub condition 即可。

建立 OIDC Provider

OIDC provider 是 AWS 帳號裡的一個資源，聲明「我信任這個外部 identity provider 簽發的 token」。GitHub Actions 的 OIDC issuer URL 是固定的，每個 AWS 帳號只需要建一個 provider。

1resource "aws_iam_openid_connect_provider" "github" {
2  url             = "https://token.actions.githubusercontent.com"
3  client_id_list  = ["sts.amazonaws.com"]
4  thumbprint_list = ["ffffffffffffffffffffffffffffffffffffffff"]
5}

client_id_list 設為 sts.amazonaws.com 是 GitHub 官方建議的 audience 值。thumbprint_list 在 2023 年之後 AWS 不再用它驗證 GitHub 的憑證鏈（改用 AWS 自己維護的根憑證清單），但欄位仍然是必填，填 40 個 f 作為佔位值即可。

這個 provider 建一次就好。多個 role 可以共用同一個 provider，差別在各自的 trust policy 怎麼寫。

Trust Policy 設計：claim 收斂

Trust policy 決定「誰能假扮這個 role」。OIDC token 裡帶有多個 claim（描述「這是哪個 repo、哪個 branch、哪個 workflow 在跑」），trust policy 用 condition 比對這些 claim，全部命中才允許 assume。

最小可行的 trust policy

 1data "aws_iam_policy_document" "ci_trust" {
 2  statement {
 3    actions = ["sts:AssumeRoleWithWebIdentity"]
 4
 5    principals {
 6      type        = "Federated"
 7      identifiers = [aws_iam_openid_connect_provider.github.arn]
 8    }
 9
10    condition {
11      test     = "StringEquals"
12      variable = "token.actions.githubusercontent.com:aud"
13      values   = ["sts.amazonaws.com"]
14    }
15
16    condition {
17      test     = "StringLike"
18      variable = "token.actions.githubusercontent.com:sub"
19      values   = ["repo:my-org/my-app:ref:refs/heads/main"]
20    }
21  }
22}

兩個 condition 各守一個邊界。aud 驗證 audience 對不對（防止其他用途的 token 被拿來 assume）。sub 驗證請求來自哪個 repo 和 branch——這是最關鍵的收斂點。

sub claim 的結構

GitHub Actions 的 sub claim 格式是 repo:{owner}/{repo}:{context}，其中 context 隨觸發方式不同：

Trust policy 的 sub condition 要根據實際需要選擇收斂到哪個層級。只允許 main branch 的 push 就寫 repo:my-org/my-app:ref:refs/heads/main；只允許 production environment 的 deploy 就寫 repo:my-org/my-app:environment:production。

environment-based 收斂（推薦）

GitHub Actions 的 environment 功能讓 sub claim 帶上 environment 名稱。搭配 environment protection rules（required reviewers、wait timer），可以在 trust policy 層和 GitHub 層各設一道 gate：

1condition {
2  test     = "StringEquals"
3  variable = "token.actions.githubusercontent.com:sub"
4  values   = ["repo:my-org/my-app:environment:production"]
5}

Workflow 裡對應的設定：

1jobs:
2  apply:
3    environment: production
4    permissions:
5      id-token: write
6      contents: read

只有 workflow 宣告了 environment: production 且通過 environment 的 protection rules 後，runner 拿到的 token 才會帶上 environment:production 的 sub claim，才能 assume 這個 role。

Plan Role 與 Apply Role 分離

把 plan 和 apply 拆成兩個 role，各自給最小權限。plan 只需要 read 權限（讀 state、讀雲端現況），apply 需要 write 權限（建立/修改/刪除資源）。分離的好處是 PR 階段的 plan 即使被攻破，攻擊者也只能讀不能改。

 1resource "aws_iam_role" "infra_plan" {
 2  name               = "infra-plan"
 3  assume_role_policy = data.aws_iam_policy_document.plan_trust.json
 4}
 5
 6resource "aws_iam_role" "infra_apply" {
 7  name               = "infra-apply"
 8  assume_role_policy = data.aws_iam_policy_document.apply_trust.json
 9}
10
11resource "aws_iam_role_policy_attachment" "plan_readonly" {
12  role       = aws_iam_role.infra_plan.name
13  policy_arn = "arn:aws:iam::aws:policy/ReadOnlyAccess"
14}

Trust policy 的差異：plan role 允許任何 branch 的 PR 觸發（repo:my-org/my-app:pull_request）；apply role 只允許 main branch 或 production environment（repo:my-org/my-app:environment:production）。

 1jobs:
 2  plan:
 3    if: github.event_name == 'pull_request'
 4    permissions:
 5      id-token: write
 6      contents: read
 7      pull-requests: write
 8    steps:
 9      - uses: aws-actions/configure-aws-credentials@v4
10        with:
11          role-to-assume: arn:aws:iam::123456789012:role/infra-plan
12          aws-region: ap-northeast-1
13      - run: terraform plan -out=plan.tfplan
14
15  apply:
16    if: github.ref == 'refs/heads/main'
17    environment: production
18    permissions:
19      id-token: write
20      contents: read
21    steps:
22      - uses: aws-actions/configure-aws-credentials@v4
23        with:
24          role-to-assume: arn:aws:iam::123456789012:role/infra-apply
25          aws-region: ap-northeast-1
26      - run: terraform apply -auto-approve

常見設定錯誤

audience 不匹配

1Error: Not authorized to perform sts:AssumeRoleWithWebIdentity

最常見的原因是 trust policy 的 aud condition 值跟 OIDC provider 的 client_id_list 不一致。兩者都要是 sts.amazonaws.com。如果用了舊版的 configure-aws-credentials action（v1），它預設用 sigstore 作為 audience，跟 sts.amazonaws.com 對不上。確認 action 版本是 v4+。

sub condition 太寬

1condition {
2  test     = "StringLike"
3  variable = "token.actions.githubusercontent.com:sub"
4  values   = ["repo:my-org/*"]
5}

這允許 my-org 底下任何 repo 的任何 branch assume 這個 role。如果組織裡有公開 repo 或 fork 權限寬鬆的 repo，攻擊者可以在那些 repo 裡觸發 workflow 來 assume 生產環境的 role。至少收斂到 repo 層級（repo:my-org/my-app:*），生產環境收斂到 branch 或 environment。

sub condition 太緊

1condition {
2  test     = "StringEquals"
3  variable = "token.actions.githubusercontent.com:sub"
4  values   = ["repo:my-org/my-app:ref:refs/heads/main"]
5}

這只允許 push to main 觸發的 workflow。PR 觸發的 workflow 拿到的 sub 是 repo:my-org/my-app:pull_request，跟這個 condition 不匹配，plan 階段會失敗。如果 plan 需要在 PR 階段跑，plan role 的 trust policy 要加 PR 的 sub pattern。

忘記設 permissions

1jobs:
2  deploy:
3    # 缺少 permissions 區塊
4    steps:
5      - uses: aws-actions/configure-aws-credentials@v4

GitHub Actions 的 OIDC token 只有在 workflow 宣告 permissions: { id-token: write } 時才會簽發。缺了這一行，configure-aws-credentials 拿不到 token，報「OIDC token not available」。這個錯誤訊息不直觀——它說的是 token 不存在，不是權限不夠。

多帳號時忘記指定 provider

如果組織有多個 AWS 帳號，每個帳號都要各自建 OIDC provider。trust policy 的 Federated principal 要指向本帳號的 provider ARN，不能跨帳號引用。跨帳號部署時，workflow 用不同的 role-to-assume 切換帳號，每個帳號的 role 各自信任同一個 GitHub OIDC issuer 但是各自獨立的 provider 資源。

測試與驗證

設定完成後的驗證步驟：

1. 手動觸發 workflow：push 一個無害的 commit 到 main、開一個 test PR，觀察 configure-aws-credentials 步驟是否成功
2. 檢查 CloudTrail：搜尋 AssumeRoleWithWebIdentity 事件，確認 source identity 和 assumed role 正確
3. 反向驗證：從一個不在 trust policy 允許範圍的 repo 或 branch 觸發 workflow，確認 assume 被拒絕
4. 權限範圍驗證：在 plan job 裡嘗試一個 write 操作（如 aws s3 rm），確認被拒絕——驗證 plan role 的 read-only 限制確實生效

1# 在 CloudTrail 搜尋 OIDC assume 事件
2aws cloudtrail lookup-events \
3  --lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRoleWithWebIdentity \
4  --max-items 5

驗證通過後，這套 OIDC 設定就取代了所有存放在 CI 環境變數裡的 access key。原有的 key 可以排程停用和刪除，排程的節奏見access key 輪替。trust policy 的持續維護重點是：新增 repo 時 sub condition 要同步更新、組織改名時 issuer 的 repo 路徑要全面修正。

時程參考：OIDC provider 建立 + trust policy 設計 + workflow 驗證約需 1-2 小時。OIDC provider 與 IAM role 本身不產生額外費用。

跨分類引用

• → 身分與憑證地基：OIDC 的概念基礎與權限邊界設計
• → infra 走 PR 流程：plan/apply 的 CI pipeline 怎麼用這裡設定好的 role
• → 跨帳號策略：多帳號環境下的 OIDC provider 配置