盤點：帳號裡有哪些 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 的儲存與引用紀律

Shared Secret rotation 的核心責任是讓 credential 換新時維持可用性、可追蹤性與可撤銷性。它表面上像是一行 SQL update，實際上牽涉 server 與多個 client 的切換時序：

• 兩邊不同時切、就斷線
• 多 client 場景下、總有一兩個沒升級
• 緊急洩漏要立即撤換、同時控制服務中斷範圍
• Rotation 中途失敗、舊新 secret 都不通

這些是維運層的真實痛點。只說「定期 rotate your secret」只能描述目標，還需要雙密期、測試、監控、通知與回退流程，才能把 rotation 變成可執行的操作契約。

本文聚焦三件事：

1. 雙密過渡期：怎麼讓 client 可以在任意時點切換、不會斷線
2. 自動化工具：AWS Secrets Manager / HashiCorp Vault / GCP Secret Manager 各自的 rotation 機制
3. 緊急 vs 定期：兩種流程的差異、何時用哪個

本文位置：本文是 API 認證的三層信任邊界 Layer 2 的深入篇。主文聚焦「為什麼系統間要獨立 credential」、本文聚焦「Shared Secret 輪替的工程實務」。

Rotation 解決什麼威脅

Rotation 是縮短 secret 暴露窗與清理殘留 access 的 lifecycle 控制。它降低三種具體威脅：

Rotation 本身有成本與風險，切換設計不完整時會造成斷線。所以實務目標是「在切換可控的前提下，選一個能接受的頻率」。

常見定期頻率：

頻率取決於威脅模型與操作能力：NIST SP 800-63B 對多數場景認可 30-90 天足夠、過於激進的 rotation 反而提高出錯機率。7-14 天適用於合規條款明文要求或私鑰可硬體保護的場景；多數 SaaS 可以停在 30-180 天區間。

「事件觸發才換」也有合理情境。純內部 cron job、secret 外流管道少、rotation 成本大於風險時，可以選擇以事件觸發取代固定排程；重點是留下 owner、inventory 與重新評估條件。

核心機制：雙密過渡期（Dual-secret Rollover）

直接 atomic 切換的失效點

最直覺的 rotation 流程是：

1T0: 兩邊都是 secret_v1
2T1: server 端換成 secret_v2
3T2: client 端換成 secret_v2

失效點出在 T1 到 T2 之間：server 只認 v2，但 client 還在用 v1，這段窗口內的 request 都會 401。即使窗口只有幾秒，production 流量也可能產生大量錯誤。

更糟的是「client 更新後忘了 reload process」這種情境 — 配置檔已改、但跑著的 server / worker process 還握著舊 secret 在記憶體裡、直到下次重啟才生效。窗口可能拉長到幾分鐘到幾小時。

解法：server 端同時接受新舊兩把

雙密過渡期把 rotation 分成 3 個階段：

 1T0：穩態
 2  server: [v1]
 3  client: [v1]
 4  狀態：v1 工作
 5
 6T1：發新 secret、server 雙密期開始
 7  server: [v1, v2]   ← server 同時接受 v1 跟 v2
 8  client: [v1]
 9  狀態：兩個都 work、client 還沒切
10
11T2：通知 client 切到 v2
12  server: [v1, v2]
13  client: [v2]       ← client 升級、開始用 v2
14  狀態：v2 work、v1 也仍 work（過渡期）
15
16T3：確認所有 client 都切完、關閉 v1
17  server: [v2]       ← 移除 v1
18  client: [v2]
19  狀態：穩態、只 v1 失效

關鍵在於 server 在 T1-T3 之間同時接受兩把 — 不論 client 在這段期間用哪一把都能通過驗證。client 可以在自己的時程內升級、不需要跟 server 切換同步。

雙密期的長度設計

雙密期是一個可用性與暴露窗的取捨。兩把同時有效時，系統需要同時保護兩把 secret，也需要追蹤兩個版本的使用比例；時間拉太短會造成 client 來不及切換，時間拉太長會擴大舊 secret 的有效窗口。

設計建議：

監控指標：在雙密期內、應該追蹤「用 v1 vs 用 v2 的 request 比例」 — 當 v1 比例降到 0%、且持續穩定一段時間後、才安全地關閉 v1。

怎麼實作「同時接受兩把」

實作模式有兩種：

模式 A：array 比對

 1VALID_SECRETS = [
 2    os.environ['SHARED_SECRET_CURRENT'],
 3    os.environ['SHARED_SECRET_PREVIOUS'],  # 可選、若在雙密期
 4]
 5
 6def verify(received):
 7    for secret in VALID_SECRETS:
 8        if not secret:
 9            continue
10        if hmac.compare_digest(secret, received):
11            return True
12    return False

這個模式適合內部固定夥伴與少量服務，因為驗證邏輯簡單、沒有額外狀態。主要風險是兩把 secret 都要部署到 server，env var / config 變多，且每個 instance 都要確認讀到相同版本。

模式 B：secret store + version

1def verify(received):
2    current_version = secret_store.get_version('shared_secret', 'current')
3    previous_version = secret_store.get_version('shared_secret', 'previous')
4    return hmac.compare_digest(current_version, received) or \
5           hmac.compare_digest(previous_version, received)

這個模式適合對外 API 或 client 數量較多的系統，因為 secret 集中管理、版本狀態可查。主要風險是驗證流程依賴 secret store，需要設計 cache、fallback 與 store 失效時的行為。

對外開放 API 通常用模式 B、可結合 AWS Secrets Manager / Vault 等工具。內部固定夥伴系統可以用模式 A 起步、複雜後再遷移。

自動化 Rotation 工具

純手動 rotation 在 client 數量增加後不可持續 — 自動化工具的價值是把「產生新 secret → 部署到 server → 通知 client → 撤銷舊 secret」整套流程程式化。

AWS Secrets Manager

機制：

• 註冊一個 Rotation Lambda、AWS 排程觸發（例如每 90 天）
• Lambda 跑 4 階段流程：createSecret → setSecret → testSecret → finishSecret
• 每個階段都有 retry、失敗會回到上一個穩態

Lambda 範例責任分工：

雙密期天然存在：AWSCURRENT + AWSPREVIOUS 兩個 staging label 同時可讀。Client 在 rotation 進行中、可以拿到 AWSPREVIOUS 作為 fallback。

適合場景：AWS 生態系、目標 service 是 RDS / Redshift / DocumentDB（有 native rotation Lambda template）或自定義（custom Lambda）。

HashiCorp Vault

Vault 有兩種 rotation 策略：

Static Secrets + Rotation Periodic：傳統 shared secret、Vault 每 N 天自動換、puts 到 vault path、client poll 拿。

Dynamic Secrets：Vault 不存 long-lived secret、每次 client 請求時臨時產生（DB credential、AWS IAM credential 等）、TTL 短（小時到天）、過期即廢。Dynamic secret 沒有 rotation 概念 — 因為每個 secret 都只活一小段時間、洩漏窗本來就有限。

適合場景：multi-cloud、不想綁 AWS、需要 dynamic secret 跨多種 backend。

GCP Secret Manager

機制較簡單 — Secret Manager 提供 versioning、每個 secret 有多個 version、client 可指定要「latest」還是特定 version。

Rotation 流程通常自己實作（GCP 沒提供類似 AWS 的 Rotation Lambda template）：

1. addSecretVersion(name, new_secret) — 加新 version
2. 部署到 server（server 同時讀 latest + previous）
3. 通知 client / 等 client 升級
4. destroySecretVersion(name, old_version) — 撤銷舊 version

雙密期靠 client 端邏輯（同時試 latest 跟 previous）實現。

適合場景：GCP 生態系、自有 rotation 邏輯不想被 vendor opinion 綁住。

三者比較

自建 rotation 系統的最小元件

小規模系統可以自建最小 rotation 元件，前提是 secret 系統本身也被視為敏感基礎設施。最小元件包含：

1. Secret 存儲：DB table secrets(id, version, value, created_at, retired_at)
2. 發放 API：GET /secrets/current 回 latest active version
3. 驗證邏輯：應用層讀 current + previous 兩個 active version
4. 排程：cron job 觸發 rotate(secret_name) — 產新 version、標記舊版 retired、設 retired_at
5. 監控：log 每個 version 被驗證的次數、舊版降到 0 後關閉

這個方案適合內部小規模系統。判斷是否可行時，要同步檢查 DB encryption at rest、access log、權限分離與備援；否則自建系統可能把 rotation 風險轉移成 secret store 風險。

緊急 rotation：洩漏發生時的流程

跟定期 rotation 的差異

定期 rotation 目標是「不中斷服務」、所以雙密期長、給 client 充分時間切換。

緊急 rotation 目標是「最快讓舊 secret 失效」 — 即使犧牲部分可用性也要立刻撤銷。兩者流程完全不同：

緊急 rotation 流程模板

 1T0: 偵測或回報洩漏
 2   ↓
 3T0+0~15min: 評估
 4   - 確認洩漏範圍（哪些 secret、影響哪些 client）
 5   - 評估「立即斷舊 secret」對 production 的影響
 6   - 決定是否走緊急流程 vs 縮短的定期流程
 7   ↓
 8T0+15min~1hr: 部署新 secret
 9   - 產生新 secret
10   - 部署到 server、開啟雙密期
11   - 主動 push 新 secret 給已知 client（內部用 channel 通知、外部 client email + dashboard）
12   ↓
13T0+1hr~24hr: 強制切換
14   - 監控用舊 secret 的 request 比例
15   - 跟未升級的 client 個別聯繫
16   - 視情境設「強制斷線時間點」並提早警告
17   ↓
18T0+24hr~72hr: 撤銷舊 secret
19   - 即使仍有 client 在用舊 secret、也斷
20   - 接受部分服務中斷、優先於 secret 繼續暴露
21   ↓
22事後: 檢討
23   - 洩漏怎麼發生（log 翻查、code audit）
24   - 偵測機制能否更快
25   - 流程哪裡可以改進

關鍵權衡：「斷線成本」vs「secret 繼續暴露的損害」。對金融、醫療等高敏感場景、寧可斷線；對非關鍵內部服務、可能可以拉長雙密期。沒有通用答案、要場景判斷。

偵測洩漏的訊號

緊急 rotation 的前提是「知道洩漏發生了」 — 但很多洩漏直到攻擊者開始用 secret 才被發現、間隔可能是幾個月。

主動偵測手段：

把這些設成監控告警、是降低「洩漏到察覺」窗口的關鍵。

多 client 的同步難題

問題本質：client 不在你的控制範圍

對外開放 API 的場景，Shared Secret 散落在第三方 client 的 server。Rotation 因此變成「怎麼讓第三方在你的時程內配合」的協調問題，不只是技術問題。

常見痛點：

• 通知 email 進垃圾匣、第三方沒看到
• 第三方的工程師離職、新接手者不知道有 rotation 排程
• 第三方的 deploy 流程慢、提前一週通知還是來不及
• 第三方根本不在線（小型客戶、半年才用一次 API）

Grace period 設計

Grace period 是「舊 secret 撤銷後、給 client 緩衝期重新申請」的機制。比硬性 deadline 更彈性：

1T0: 公告 rotation、雙密期開始
2T0+30天: 雙密期結束、舊 secret 撤銷
3T0+30~60天: Grace period
4   - 用舊 secret 的 request 回 410 Gone（或 401 + 可讀的 error code，視 API 慣例）+ 連結到 "secret expired" 頁
5   - 提供 self-service 重設 secret 的流程
6   - 仍然斷線、但 client 知道怎麼自己救
7T0+60天: 完全關閉、需要重新申請新 client account

Grace period 的關鍵是在拒絕舊 secret 的同時，提供足夠資訊讓 client 自助修復。判讀訊號是錯誤回應是否能指出 secret 已過期、去哪裡重設、何時完全關閉；若只回無上下文的 401，client 仍會被導向錯誤排障路徑。

強制升級的工具

對於必須統一升級的場景（例如安全合規要求）、有幾種強制手段：

失敗模式與緩解

失敗 1：雙密期太短、client 沒升級

症狀：rotation 後第二週，某 client 開始 401，才發現他沒收到通知或尚未升級。

緩解：

• 雙密期至少覆蓋「最大已知 client 的 deploy cycle」
• 雙密期內監控「用舊 secret 的 client 數量」、降到 0 才關
• 緊急 rotation 例外、要事先評估可接受的斷線成本

失敗 2：rotation 中斷、新舊都不通

症狀：deploy 新 secret 到 server 中途失敗、一半 server 是新、一半是舊 — request 隨機 401。

緩解：

• 部署用 rolling update、確認每個 instance 都生效再進下一個
• 部署前確認「server 是雙密 mode」、即使部署到一半也能容錯
• 保留快速 rollback 機制（10 分鐘內能 revert）

失敗 3：新 secret 沒測通就上線

症狀：新 secret 部署完、第一個 client 試了發現格式不對 / 長度限制 / 特殊字元編碼問題、大量 401。

緩解：

• Rotation 流程加 testSecret 階段（AWS Lambda 模式）— 切換前用新 secret 跑一輪驗證 request
• Staging 環境先跑完整 rotation 流程、再上 prod
• 新 secret 的 format 跟舊一致（同長度、同字元集）、減少 client 端的 parsing 風險

失敗 4：Rotation 缺少 owner、secret 長期暴露

症狀：上次 rotate 已是 3 年前，原本的負責人離職，接手者不知道有這個 secret 存在。

緩解：

• Secret 管理工具強制設 expires_at、過期前自動提醒
• Inventory 表：所有 production secret 列管、定期 audit
• Rotation 排程進 calendar、輪值負責

失敗 5：rotation 後 audit log 沒更新

症狀：洩漏發生、要追「這個 secret 給過誰用」、但 audit log 只記了「secret 被用了」、沒記版本、無法區分新舊。

緩解：

• Audit log 記 secret version、不只 secret 本身
• Rotation 事件本身也要 log（誰、什麼時候、為什麼）
• Log 保留期跨多次 rotation cycle、避免歷史追溯斷鏈

收尾

Shared Secret rotation 的本質是有意識管理 secret 的 lifecycle。從發放、儲存、輪替到撤銷，每個階段都有對應的工程設計與監控訊號。

幾個核心原則：

1. 雙密過渡期是底層機制 — 任何 rotation 方案都建立在「server 能同時接受兩把」之上
2. 自動化工具值得投資 — 規模小用 secret manager（AWS / Vault / GCP），規模大可以自建，避免停在純手動
3. 定期跟緊急是兩套流程 — 定期重不中斷，緊急重立刻撤，流程、通知與回退標準要分開
4. 多 client 是協調問題 — 比技術問題難解、grace period + 強制升級工具是常用解法
5. 失敗模式要演練 — production 第一次跑 rotation 前，先在 staging 演練完整流程與回退路徑

延伸閱讀：

• API 認證的三層信任邊界 — 本文的主篇、Shared Secret 在「Layer 2 系統層」的位置
• Laravel Sanctum 的 Bearer Token 設計剖析 — Layer 1 使用者 token 的儲存原則（hash + constant-time）也適用於 Layer 2
• mTLS 實際怎麼設定與運維 — 不用 shared secret 的另一條路、憑證 lifecycle 跟 secret lifecycle 的對照