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 設定

IAM 的心智模型

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

identity 分兩類，這個區分在後面設計權限邊界時會反覆用到。一類是 user，代表一個長期存在的主體，通常對應到一個真人或一個固定的服務帳號，本身可以持有長期憑證。另一類是 role，代表一組權限的暫時授予 — 沒有自己的長期密碼，而是讓某個被信任的身分「假扮（assume）」成它、換取一段有時效的臨時憑證。policy 則是貼在 user 或 role 上的規則文件，列出 Action（能做什麼，如 s3:GetObject）、Resource（對哪個資源）、Effect（允許或拒絕）。

最小權限（least privilege）是貫穿這套系統的設計原則：一個身分只應該拿到完成它本職工作所需的最小權限集合，多一個 action、多一個 resource 都是攻擊面。最小權限是持續收斂的過程，而非一次設定就結束的靜態狀態 — 服務初期常為了快速上線給寬鬆權限，之後要靠 access analyzer 這類工具觀察「實際用到哪些 action」，再把沒用到的權限收掉。判讀訊號很直接：如果一個 CI role 的 policy 裡有 *:* 或 AdministratorAccess，它就是下一個 incident 的入口。

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

長期 access key 的風險

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

第一是散落。長期 key 為了被程式使用，會被複製進 .env 檔、CI 設定、本機 ~/.aws/credentials、Slack 訊息、甚至誤推進 git 歷史。每多一個副本就多一個外洩點，而你很難盤點清楚一把 key 到底被貼進了多少地方。第二是權限過大。因為輪替麻煩，團隊傾向給一把 key 配足夠寬的權限「一次搞定」，於是一把本來只該讀 artifact 的 key 同時握有刪除 production 資料庫的能力。第三是難以輪替。輪替一把長期 key 意味著找出所有副本、同步替換、確認沒有遺漏，這個成本高到讓多數團隊選擇拖延，於是 key 的有效期變成「無限」，外洩後的曝險窗口也跟著變成無限。

判讀訊號是：如果你無法在五分鐘內回答「這把 key 被用在哪些地方、上次輪替是什麼時候」，它就已經是技術債。早期新創特別容易踩這個坑 — 一個工程師為了讓部署腳本跑起來，在筆電上建了一把 admin key，半年後這把 key 還在 CI 環境變數裡，建立它的人已經離職。這類事故的代價不在於「key 外洩」這個事件本身，而在於外洩之後你沒有任何手段限制爆炸半徑。

OIDC：給 CI/CD 的短期憑證

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

關鍵設計在 role 的 trust policy（信任政策）上 — 它規定「哪個外部身分被允許假扮成這個 role」。trust policy 要用 token 的 claim 把假扮條件收到最緊：限定 issuer、限定 audience、限定特定 repo 與 branch。收得太鬆（例如只驗 issuer、不驗 repo）等於任何掛在同一個 CI 平台的專案都能假扮你的 role，這是常見的設定陷阱。

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

這一章只把 role 與 trust policy 設計好，OIDC 的實際回報要到模組七：infra 走 PR 流程建管線時才兌現 — 屆時管線用這裡定義好的 role 取得短期權限執行 plan 與 apply，CI 環境裡不需要存任何 access key。下一步路由很明確：role 與最小權限的 policy 屬於這裡的地基，管線怎麼觸發、怎麼卡 review 屬於模組七。

權限邊界設計

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

人 vs 機器的邊界，源自兩者的存取模式根本不同。人類身分需要互動式登入、應該強制 MFA、權限隨職責變動，且通常透過 SSO 集中管理而非各自持有 key。機器身分（CI、跑在運算資源上的服務）需要的是程式化、無人值守的存取，應該用 role 假扮取得短期憑證，永遠不該配長期 key。機器身分還要再分跑在哪裡：跑在雲上的 workload（運算實例、容器任務）由平台直接把 role 綁在執行環境上 — AWS 用 instance profile 把 role 掛在 EC2 instance、用 ECS task role 把 role 掛在容器任務，workload 從實例 metadata 自動取得輪替的短期憑證，這是早於 OIDC 就存在的標準解；只有跑在雲外的 CI/CD（如 GitHub Actions）拿不到實例 metadata，才需要前面那套 OIDC 信任關係換憑證。把這兩類混在同一個身分上，會讓你既無法對人強制 MFA，也無法對機器收斂權限。一個常見陷阱是工程師用自己的個人 key 跑自動化腳本 — 這把人的廣泛權限直接送進了無人值守的執行環境。

環境之間的邊界，目的是讓 production 的權限與 staging、dev 完全不交叉，避免一次誤操作或一個被攻破的低敏感環境波及到核心資產。實作上常見的做法是每個環境用獨立的帳號（account）或獨立的 role，部署到 production 的身分拿不到 staging 的資源、反之亦然。這條邊界在 AWS 上有兩層具體機制可以落地：帳號級的護欄用 Organizations 把環境拆成獨立帳號，再用 SCP（Service Control Policy）對整個帳號或組織單位設定權限天花板，連帳號內的管理員都越不過去；role 級的護欄用 Permissions Boundary 這個 IAM 字面功能，給單一 role 設一個權限上限，限制它「最多能拿到什麼」，即使有人後來給它貼了過寬的 policy 也會被天花板擋住。前者收的是帳號與組織的整體範圍，後者收的是單一身分的上限，兩者疊起來才讓「權限邊界」從概念變成擋得住誤設的具體工具。判讀訊號是：如果一個 dev 環境的 CI role 能列出或刪除 production 的資源，邊界就沒有真正建立。環境隔離的更完整實作（帳號結構、模組化參數）會在模組四：環境分離與模組化展開，這裡先確保身分層的權限不跨環境。

這一章談的是身分與憑證 — 誰是誰、怎麼證明、能動什麼。憑證背後引用的應用層 secret（資料庫密碼、第三方 API key）怎麼安全儲存與注入，屬於模組八：治理好習慣的 secret management 範圍，不在這裡處理。兩者的交集是：身分層決定「誰能讀到 secret store」，secret 層決定「secret 怎麼存與輪替」。

章節文章

跨分類引用

• → 模組三：網路地基：身分備妥後，劃清服務之間的網路邊界
• → backend 模組七：資安與資料保護：Secret Management 與這裡的憑證管理交集
• → 模組七：infra 走 PR 流程：CI/CD 用 OIDC 取得短期權限
• → 接手維運：接手時的 credential 盤點與輪替

本篇以 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 配置

概念位置

OIDC 聯合在身分與憑證地基裡的角色是「雲外機器身分的認證機制」。跑在雲上的 workload（EC2、ECS task）可以用平台原生的 instance profile 或 task role 取得短期憑證；跑在雲外的 CI/CD 沒有這個管道，OIDC 就是替代方案。

運作方式是建立信任關係：雲端帳號信任某個外部 identity provider（如 GitHub Actions 的 OIDC issuer），CI 執行時平台簽發一個帶 claim 的 token（描述哪個 repo、哪個 branch、哪個 workflow），雲端用這個 token 換出一段臨時憑證。

可觀察訊號

以下狀況指向 OIDC 相關問題：

• CI pipeline 裡有 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 環境變數 — 這是長期 key，應該替換成 OIDC
• Trust policy 只驗 issuer 不驗 repo — 任何掛在同一個 CI 平台的專案都能假扮這個 role
• Pipeline 突然無法取得權限 — 可能是 trust policy 的 condition 跟 token claim 不匹配（常見於 repo 改名或 branch 改名後）

設計責任

設定 OIDC 聯合時要決定：

• Trust policy 的 claim 收斂：限定 issuer + audience + 特定 repo + 特定 branch，每個條件都收到最緊
• Role 的權限範圍：OIDC 換到的 role 仍然要遵循最小權限 — 只給 pipeline 需要的 action
• Plan 與 apply 分開的 role：plan 只需要 read 權限、apply 需要 write 權限，用兩個 role 降低 PR 階段的風險

鄰卡

• IAM — OIDC 是 IAM 身分系統的一種外部身分來源
• Security Group — OIDC 解的是身分層的認證問題，跟網路層的 security group 正交