服務定位

Vault 的核心定位是 跨雲 + 跨環境 + 跨 secret 形態的單一 secret 控制面。當組織同時跑 AWS + GCP + on-prem K8s、又需要 dynamic database credential + 內部 PKI + envelope encryption、用三個 cloud-native service 拼起來會出現 secret 治理鏈不連續（AWS 的 secret 怎麼授權 GCP service 取用、on-prem app 怎麼拿短期 cloud credential、內部 CA 跟外部 ACM 怎麼分工）。Vault 把這層 統一抽象 — 應用端只跟 Vault 講話、Vault 後端接各雲 KMS / database / PKI。

跟 AWS Secrets Manager / Google Secret Manager 相比、Vault 多了：dynamic credential engine（cloud-native 對應產品有限）、transit engine 做 encryption-as-a-service、PKI engine 自簽內部憑證、跨雲統一介面。代價是 自管運維（HA cluster、auto-unseal、replication、upgrade）— 跟自管 Keycloak 的取捨同類。HCP Vault（HashiCorp Cloud Platform）是 HashiCorp 託管版、把運維交還、但綁 HashiCorp。

本章目標

讀完本頁、讀者能判斷：

1. 哪些 secret 適合 Vault（dynamic credential、跨雲、PKI、encryption-as-a-service）、哪些直接用雲端 native service 即可
2. Vault deployment 的最低安全需求（auto-unseal、HA、audit device、policy、replication）
3. Vault 自己出事時的降級路徑（seal storm、root token 復原、audit log gap）
4. 何時用 Vault、何時走 Secrets Manager / Google Secret Manager / Azure Key Vault 的取捨

最短判讀路徑

判斷 Vault deployment 是否健康、最少看五件事：

• 誰能做什麼：root token 是否已 revoke、policy 是否走 path-based least privilege、admin 是否走 OIDC / AWS IAM auth 而不是 token、break-glass token 是否離線存
• Auth method 收緊：AppRole / Kubernetes / OIDC / JWT auth 哪些開、role 對應的 policy 是不是過寬、TTL 是否短、bound_* 條件是否鎖（namespace / audience / subject）
• Secret engine 設定：KV v2 開 versioning？dynamic engine（database / aws / pki）lease TTL 多久、max TTL 限制是什麼、revocation 是否驗證生效
• Seal / unseal 治理：是否走 auto-unseal（KMS-backed）、recovery key 持有者跟 Shamir threshold、replication 跟 DR cluster 是否同步
• 證據是否可回查：audit device（file / syslog / socket）是否多 channel、是否同步到 SIEM、replay 攻擊防護是否開（HMAC + nonce）

五件事任一缺失、就是 Audit Log 與 Secret Management 邊界的待補項目。

日常操作與決策形狀

Auth method 設計：AppRole 適合不在雲端 metadata 內的 workload（on-prem、CI runner）但 secret_id 本身要妥善保管；Kubernetes auth 適合 K8s 內 workload、用 ServiceAccount token + projected token；AWS IAM auth 適合 AWS 內 workload、走 STS 簽名驗證、不需要存 secret；OIDC / JWT 適合 human admin + CI（GitHub Actions / GitLab CI 走 OIDC token）。每個 auth method 對應 一組 role、role 綁 policy 跟 TTL。

Secret engine 分層：KV v2（static secret + version history）作為基線；dynamic database engine（PostgreSQL / MySQL / MongoDB）發短期 DB user、max_ttl = 1h 級別、過期 Vault 自動 revoke；AWS / Azure / GCP secret engine 對 cloud account 發短期 STS credential / service account key；PKI engine 自簽憑證、跟 cert-manager 整合做 K8s workload mTLS；transit engine 做 envelope encryption — app 把資料丟給 Vault 加密、key 不離 Vault。

Policy（path-based）：Vault policy 是 path + capabilities（create / read / update / delete / list / sudo）的 mapping。常見錯配：給 secret/* read 等於整個組織所有 secret 都看得到、應該用 secret/data/{team}/* 之類前綴限定；admin policy 不要給 sudo 太寬、policy 變更走 PR review + CI apply。

Rotation 跟 lease 治理：static secret（KV）的 rotation 是 app 自己做（拿新 secret 後手動 update）；dynamic secret 是 Vault 控制 lease 生命週期、app 只要在 TTL 內續租即可。對應 Failure: Credential Rotation Without Scope：static secret 的 rotation 必須有 scope map — 哪些 service 用了同一把 secret、哪個 service 支援零停機 rotation、誰是 last to be rotated。沒這份 map 就會發生「rotate 後某個被遺忘的 cron job 認證失敗、整個下游崩」。

Seal / unseal 設計：Vault 啟動時 sealed、必須 unseal 才能服務。Shamir secret sharing 是預設（5 key holders、3 threshold）— 任何重啟需要找齊 3 個人合 unseal、production 場景幾乎都該換 auto-unseal（用 AWS KMS / GCP KMS / Azure Key Vault 當 master key custodian）。代價是 把 master key 託給雲廠 — 不接受的組織保留 Shamir + 嚴格 key holder rotation。

Audit device 是 必開：Vault 預設不開 audit、要手動 enable（vault audit enable file path=/var/log/vault_audit.log）。沒 audit device 在 production = 事故時 連 token 被誰用過都查不到。建議多 channel（file + syslog + 推到外部 SIEM）— 單一 channel 失效（disk full、socket broken）Vault 會拒絕請求、影響 availability、所以多 channel 是必要冗餘。

Break-glass 與 root token：初始化時產生的 root token 應該 用完立刻 revoke、改用 admin policy + OIDC auth。break-glass scenario 用 recovery key 重新發 root token、recovery key 走 Shamir 多人持有 + 離線存。

核心取捨表

選 Vault 的核心訴求：跨雲 + dynamic credential + 內部 PKI + transit encryption 至少滿足兩項、且能投入 SRE 量能跑 HA cluster、有 SIEM 接 audit log、能接受 self-hosted 的 upgrade / cert / DB 運維成本。單純需要 AWS-only static secret rotation、直接用 Secrets Manager 更便宜更簡單。

進階主題

Dynamic credential 的 lease 生命週期治理：dynamic engine 發出的 credential 都帶 lease ID、Vault 在 TTL 到期時自動 revoke（database engine 真的會 DROP USER、cloud engine 真的會 DeleteAccessKey）。設計時要算清楚 app 連線池的 connection lifetime — DB connection 持續用同一組 credential、credential lease 過期但 connection 還在會出現 staled credential 問題。常見作法：lease TTL > connection idle timeout * 2、加 lease renewal mechanism（app 在 TTL 50% 時主動 renew）。

Transit engine（encryption-as-a-service）：app 不持 encryption key、把 plaintext 丟給 Vault encrypt API、拿 ciphertext 回來；解密時把 ciphertext 給 Vault decrypt API。Key 完全不離 Vault、所有 cryptographic operation 在 Vault 內、app 只需要 encrypt / decrypt capability。對應 Storm-0558 signing key chain 的對照啟示：key 不能 export 是減 blast radius 的關鍵設計 — transit 把這個原則內建。

PKI engine + cert-manager 整合：Vault PKI engine 可以當內部 root CA + intermediate CA、issue 短期 cert（hours-level）給 K8s workload；cert-manager 用 Vault PKI issuer 自動更新 cert。比起手動跑 OpenSSL CA、Vault PKI 的優勢是 cert lifecycle 進 Vault audit、跟 secret rotation 用同一套 evidence chain（呼應 credential rotation scoped evidence）。

Namespace（Enterprise）跟 multi-tenancy：Enterprise 版 namespace 是 tenant 邏輯隔離、每個 namespace 有自己的 auth method、policy、secret engine。OSS 版沒 namespace — 多團隊共用 Vault 要靠 path 命名規約 + policy prefix 拼隔離、邊界較鬆。大組織通常需要 namespace 才能避免單一 admin 跨 team 越界。

Replication（Enterprise）：Performance Replication（主從 + 多 region active）跟 DR Replication（純 standby）是兩個獨立功能。production HA 通常需要 同 region 的 cluster + 跨 region 的 DR replication、recovery key 跟 unseal 機制要跨 cluster 一致。

排錯與失敗快速判讀

• Audit device 沒開：production 啟動時忘了 enable audit、事故發生時無 forensic data — 啟動 checklist 必含「enable audit before serving traffic」、SRE runbook 用 health check 驗
• Policy 過寬：給整個 secret/* read、單一 token 等於拿到全公司 secret — 用 path prefix 限定到 {team}/{env}/*、policy review 走 PR
• Dynamic credential lease 太長 / 沒 max_ttl：DB user 跑了一週還沒收、攻擊者只要拿到一次就長期可用 — 設定 lease TTL = 1h、max_ttl = 24h
• Auto-unseal KMS access 沒監控：AWS KMS / GCP KMS 的 Vault auto-unseal key 沒 alert 異常使用 — KMS 端設 alert（GetKeyValue / Decrypt 突增）
• Replication lag 沒 alert：Performance / DR replication 落後幾分鐘到幾小時、failover 時拿到 stale state — Prometheus 監控 vault.replication.* metric
• Root token 未 revoke：初始化時的 root token 還在用、policy / audit / OIDC 全 bypass — 初始化 checklist 強制 revoke、CI 跑 vault token lookup 驗證 root 不可用
• Sealed 後 unseal key 找不到人：production cluster 緊急 restart、Shamir threshold 3 但有 1 個 key holder 在度假 — production 必須 auto-unseal、recovery key 走 break-glass 流程

何時改走其他服務

不在本頁內的主題

• Vault 完整 API reference 跟 CLI 詳盡用法
• 每個 secret engine 的內部實作細節（DB connection pool、cloud SDK 呼叫順序）
• Enterprise 各 license tier 的功能對照
• Terraform / Ansible 跟 Vault 整合的完整步驟
• 各 auth method 的 OIDC / SAML provider 設定教學

案例回寫

Vault 在 07 案例庫沒有直接 vendor-level 事件、以下案例採對照引用：

下一步路由

• 上游：7.6 秘密管理與機器憑證治理、7.13 偵測覆蓋率與訊號治理
• 平行：AWS Secrets Manager、Google Secret Manager、Azure Key Vault
• 下游：AWS KMS / Google Cloud KMS（Vault auto-unseal master key custodian）
• 下游：cert-manager（用 Vault PKI engine 作為 K8s workload cert issuer）
• 跨模組：8 事故處理 vendor 清單（Vault 事件如何 routing 進 IR 流程）
• 官方：Vault Documentation

服務定位

Secrets Manager 的定位是 AWS-only workload 的 static secret 控制面、跟 SSM Parameter Store SecureString 在 存 secret 這層功能重疊、但設計目的不同。Parameter Store 是 parameter 管理（free tier、advanced parameter 每 10000 個約 $0.05、KMS 加密但無 staging label 與 rotation Lambda）；Secrets Manager 是 secret 管理（每個 secret per month $0.40 + API call、有 staging label / rotation Lambda / Resource Policy / Cross-Region Replica）。價差 8 倍以上、選擇基準在 是否需要 rotation 跟 cross-account sharing。

跟 Vault 比、Secrets Manager 是 單一雲、簡單、低運維、Vault 是 跨雲、dynamic credential、高表達力。AWS-only 組織用 Vault 等於多扛一個 HA cluster 運維成本只為了拿 KV engine 跟 RDS rotation、ROI 不划算；反向跨雲組織用 Secrets Manager 等於每個雲都自己一套 secret store、治理鏈會斷。跟 Google Secret Manager / Azure Key Vault 比、設計理念類似（雲廠 managed、KMS 加密、IAM 授權）但 rotation 機制各家不同 — Secrets Manager 用 built-in Lambda 四階段 flow、GSM 用 Pub/Sub event 觸發自寫 Cloud Function、Azure 用 Key Vault rotation policy + Event Grid。

本章目標

讀完本頁、讀者能判斷：

1. 哪些 secret 用 Secrets Manager、哪些可以下放到 Parameter Store、哪些該走 Vault 的 dynamic credential
2. Secrets Manager 的 雙層 grant 模型（Resource Policy + IAM Policy）跟 KMS encryption key custody 怎麼配
3. Built-in rotation 跟 Custom Rotation Lambda 的設計邊界、staging label 在 zero-downtime rotation 內的角色
4. 何時 Secrets Manager 已經不夠用、要往 Vault / 跨雲 broker 走

最短判讀路徑

判斷一個 Secrets Manager 部署是否健康、最少看四件事：

• 誰能 GetSecretValue：IAM Policy 那邊是不是用 secretsmanager:GetSecretValue 限定到 特定 secret ARN（不是 *）、Resource Policy 是不是只允許特定 principal（不是 Principal: *）、跨帳號 share 有沒有用 ABAC tag 限縮
• KMS key custody：secret 用 AWS-managed key（aws/secretsmanager）還是 customer-managed key（CMK）— production 應該全部 CMK、key policy 限定 only Secrets Manager service principal 可用、KMS key 持有者跟 secret 持有者要分離
• Rotation 設定：rotation 開了沒、rotation interval 多久、Lambda 過去執行 success rate、staging label 在 rotation 過程中是否依序 promote（AWSPENDING → AWSCURRENT → AWSPREVIOUS）
• CloudTrail data event：GetSecretValue 是 Data event、預設不記、要手動開 data event logging — 沒開等於事故時看不到 誰拿了 secret、只看得到 management API（CreateSecret / UpdateSecret）

四件事任一缺失、就是 Secret Management 跟 Audit Log 邊界的待補項目。

日常操作與決策形狀

Resource Policy + IAM Policy 雙層 grant：Secrets Manager 跟 S3 bucket policy 同模型 — IAM Policy 控制 principal 端能做什麼、Resource Policy 控制 secret 端允許誰來、兩者要 都同意 才放行。常見錯配：Resource Policy 寫 Principal: "*" 加 aws:SourceAccount condition 想做跨帳號 share、但 condition 漏寫或寫錯就變成公開可讀。跨帳號 share 一定要明確列 Principal: arn:aws:iam::123456789012:role/AppRole、不要靠 wildcard + condition 拼隔離。

IAM Policy 細粒度授權：secretsmanager:GetSecretValue 該限定到 specific secret ARN（不是 *）、配合 ABAC tag condition（secretsmanager:ResourceTag/team = payments）限縮 blast radius。對應 CircleCI 2023 Secrets Rotation — CI 出事時要能依 tag 快速列出 CI runner 可拿的所有 secret、沒這套 tag 就只能盲目 rotate 全部。

KMS encryption key 選 CMK 不是 default：每個 secret 用一把 KMS key 加密、預設用 AWS-managed key aws/secretsmanager、production 應該換 customer-managed key（CMK）。差別在 key policy 是不是自己控 — AWS-managed key 的 policy 同 account 任何 service 可呼叫、CMK 的 key policy 可以鎖到 only Secrets Manager service principal 加 only specific role 可 Decrypt。對應 Storm-0558 的對照啟示：key 的 blast radius 來自 key policy、用 CMK 把 policy 寫窄是減 blast radius 的關鍵動作。

Built-in Rotation Lambda 只限 AWS native DB：Secrets Manager 內建 rotation template 涵蓋 RDS（PostgreSQL / MySQL / MariaDB / Oracle / SQL Server）/ Aurora / Redshift / DocumentDB — 拿 AWS 提供的 Lambda template、設定 rotation interval（最短 1 天、最長 365 天）、Secrets Manager 自動排程觸發。其他 DB（self-hosted PostgreSQL、MongoDB Atlas、Snowflake）或 API key 要寫 Custom Rotation Lambda、走 4-step state machine：createSecret（產新 credential 存為 AWSPENDING）、setSecret（把新 credential 寫到 target system）、testSecret（用新 credential 驗證可連）、finishSecret（promote AWSPENDING → AWSCURRENT）。Lambda 任一步失敗 Secrets Manager 會 rollback、舊 credential 不受影響。

Staging Label（AWSCURRENT / AWSPENDING / AWSPREVIOUS）：staging label 是 指向 version 的 pointer、app 一律用 GetSecretValue 不帶 VersionStage 拿 AWSCURRENT、rotation 過程中 Secrets Manager 先把新 credential 標 AWSPENDING、testSecret 過後 promote 到 AWSCURRENT、舊的降到 AWSPREVIOUS。設計初衷是 zero-downtime rotation — 但 只有 app 端支援 AWSPREVIOUS fallback 期間才有意義：rotation 完成瞬間有些 app instance 還拿著舊 credential，target system 應該同時接受 AWSCURRENT 跟 AWSPREVIOUS（DB rotation template 會在 setSecret 階段保留舊 user 一段時間）。對應 Failure: Credential Rotation Without Scope：scope map 沒做、AWSPREVIOUS 窗口期太短、長尾 batch job 拿到舊 credential 就掛。

Cross-Region Replica：multi-region app 把 secret replicate 到其他 region、replica 在 replica region 有獨立 ARN、KMS key 跟 rotation 都要在 replica region 各自配（不能跨 region 共用 KMS key）。replica 是 讀副本、寫只能在 primary region、rotation 觸發後新 version 自動 sync 到 replica（有秒級延遲）。failover 時 app 直接讀 replica region ARN、不需要 cross-region call。

Cross-Account Sharing：跨帳號 share secret 走 Resource Policy + 對方帳號 IAM Policy 雙向授權 — Resource Policy 列對方 account 的具體 role ARN、對方 role 的 IAM Policy 加 GetSecretValue 對應 ARN。KMS key 也要跨帳號授權（KMS key policy 加對方 role 的 Decrypt 權限）— 漏了 KMS 授權會出現 GetSecretValue 成功但 Decrypt 失敗 的詭異錯誤。

核心取捨表

選 Secrets Manager 的核心訴求：AWS-only + 大部分 secret 是 static 或 AWS native DB credential + 需要 cross-account share 或 rotation Lambda + 不想 / 沒量能自管 Vault。如果只是要存 config（feature flag、non-sensitive endpoint）、Parameter Store 8 倍便宜；如果跨雲 + 需要 dynamic credential / transit / PKI、Vault 才能滿足。

進階主題

Custom Rotation Lambda 設計：4-step state machine 是 idempotent contract — Lambda 必須能被 Secrets Manager 重試任意步驟而不破壞狀態。常見實作陷阱：createSecret 不檢查 AWSPENDING 是否已存在、重試時又產生一把新的、AWSPENDING 對不上 setSecret 寫進去的；setSecret 沒處理「target system 已經有同名 user」的情況、第二次跑會卡住。Template 提供的 PostgreSQL rotation Lambda 用 cloning approach — 在 DB 內 clone 一份 user、改密碼、保留舊 user 跨 rotation 一個週期、下次 rotation 才 drop。

Resource Policy + ABAC tag 跨帳號：跨帳號 share 時用 ABAC tag 條件比硬列 role ARN 有彈性 — Resource Policy 寫 Condition: aws:PrincipalTag/team = payments、對方 account 任何帶該 tag 的 role 都可讀。代價是 tag 治理 變成 critical control：對方 account 內誰能 attach tag = 誰能拿 secret、IAM Policy 要鎖 iam:TagRole 跟 iam:UntagRole 權限。

Rotation 失敗的監控訊號：Lambda 執行失敗會在 CloudWatch 留 invocation error、Secrets Manager 把 rotation 標記為 failed、但 secret 仍可用（AWSCURRENT 保留舊 version）— 容易出現 半年沒 rotate 成功但 app 看起來正常 的盲區。要監控 SecretsManager.RotationFailed event（EventBridge rule）+ LastRotatedDate metric 超過 rotation interval 1.5 倍就 alert。

跟 AWS IAM 整合：誰可以 GetSecretValue 完全由 IAM 控制、最佳實踐是 workload role 拿 secret（EC2 instance role / ECS task role / Lambda execution role / EKS IRSA）、不要硬把 AWS credential 塞進 secret 再給 application read。Secret 內容應該是 DB password / API token / third-party credential、不應該是 AWS credential（AWS credential 用 IAM role 短期 STS 拿就好）。

CloudTrail data event 的成本權衡：開 GetSecretValue data event 等於每次 secret 取用都進 CloudTrail、高 QPS application 一天可能跑數百萬筆、CloudTrail 成本（每 100k events 約 $0.10）跟 S3 儲存成本會明顯上升。降本作法：在 EventBridge 用 filtering（只送特定 sensitive secret 的 data event 到 SIEM）、CloudWatch Logs 端設 retention 短一點（7-30 天熱資料、長尾走 S3 + Athena）。

排錯與失敗快速判讀

• GetSecretValue AccessDenied 但 IAM Policy 看起來對：檢查 Resource Policy 是否限定 source account / VPC、檢查 KMS key policy 是否允許該 role Decrypt — 兩層 grant + KMS 三點任一缺都會 AccessDenied
• 跨帳號 secret 拿不到：Resource Policy 沒列對方 role、或 KMS key policy 沒給對方 Decrypt 權限 — 跨帳號要同步配三處（Resource Policy + 對方 IAM + KMS key policy）
• Rotation 一直失敗但沒人發現：沒設 EventBridge alert on RotationFailed、AWSCURRENT 保持舊 version、app 正常但 secret 過期 — 必設 LastRotatedDate metric alert
• App 拿到 stale secret rotation 後爆掉：app 端用了 SDK cache（如 AWS SDK 的 Secrets Manager Cache）、rotation 完成後 cache 沒 invalidate — cache TTL 要短於 staging label 重疊窗口、或實作 retry-on-auth-fail 觸發 cache refresh
• CloudTrail 看不到誰拿 secret：沒開 data event logging — 在 CloudTrail trail 設定加上 AWS::SecretsManager::Secret 為 data resource
• 跨 region replica rotation 失效：rotation Lambda 只在 primary region 配、replica region 沒對應 Lambda — 每個 region 各自配 Lambda、或乾脆只在 primary rotate 讓 replica 自動 sync
• AWSPREVIOUS fallback 沒生效 batch job 掛：rotation Lambda finishSecret 太快 drop 舊 user、batch job 拿到舊 credential 連 DB 失敗 — DB rotation template 預設保留舊 user 一個 rotation 週期、custom Lambda 要自己實作雙軌窗口

何時改走其他服務

不在本頁內的主題

• Secrets Manager 完整 API reference 跟 SDK 用法
• 每種 RDS engine 的 rotation Lambda template 內部 SQL 細節
• AWS pricing 詳細計算（每 region 略有差異）
• Terraform / CDK 跟 Secrets Manager 的 IaC 整合
• AWS account organization / SCP 怎麼限制 secret 建立

案例回寫

Secrets Manager 在 07 案例庫沒有直接 vendor-level 事件、以下案例採對照引用：

下一步路由

• 上游：7.6 秘密管理與機器憑證治理、7.13 偵測覆蓋率與訊號治理
• 平行：HashiCorp Vault、Google Secret Manager、Azure Key Vault
• 下游：AWS KMS（Secrets Manager 加密 key custodian、CMK 與 key policy 治理）
• 下游：AWS IAM（誰可以 GetSecretValue、跨帳號 share 的 principal 來源）
• 跨模組：8 事故處理 vendor 清單（secret 外洩事件如何 routing 進 IR 流程）
• 官方：AWS Secrets Manager Documentation

服務定位

GSM 的定位是 GCP-native 的 secret 集中點、解決三件事：把 secret 從 environment variable / Cloud Build substitution / GitHub secret 收回單一受控位置；用 Google Cloud IAM 的 role binding on secret resource 控制誰能讀；走 Workload Identity Federation 讓 GKE / Cloud Run / 外部 workload（GitHub Actions / AWS / Azure）安全取用、避免長期 service account key 散落。

跟 Vault 比、GSM 沒有 dynamic credential engine、沒有 transit / PKI engine、沒有跨雲統一介面 — 但運維成本接近於零、跟 GCP IAM / KMS / Cloud Logging 的整合是 first-class。跟 AWS Secrets Manager 比、GSM 把 rotation orchestration 推給應用層、自由度高但代價是 rotation 流程要自己設計；跟 Azure Key Vault 比、兩者 mindset 相近（單雲、IAM-driven、CMEK 整合）、各自綁雲。

本章目標

讀完本頁、讀者能判斷：

1. 哪些 secret 適合 GSM（GCP-only、static、靠 IAM 授權即可）、哪些該走 Vault 或其他雲端 native
2. GSM 最低安全設定（CMEK、Data Access audit、Workload Identity Federation、IAM Conditions）
3. 自寫 rotation Cloud Function 時必須處理的 版本切換窗口 跟 fallback 邏輯
4. 何時 GSM 不夠用、要往 Vault / Berglas / Cloud HSM 走

最短判讀路徑

判讀一個 GSM deployment 是否健康、最少看四件事：

• 誰能讀 secret：secret resource 上的 IAM binding 是不是用最小單位授權（per-secret、不是 project-level roles/secretmanager.secretAccessor）、有沒有上 IAM Conditions 限定時間 / IP / resource tag
• Key custody 分離：encryption key 是 Google-managed default key、還是 Cloud KMS CMEK？CMEK 的 key 持有 admin 跟 secret access admin 是不是分人
• 取用路徑：workload 取 secret 是走 service account key（壞模式、長期憑證散落）還是 Workload Identity Federation（GKE WIF / 外部 OIDC token exchange）
• 證據是否可回查：Admin Activity audit 預設開、Data Access audit（AccessSecretVersion 誰呼叫）預設 關、production 要手動 enable + 接 Cloud Logging sink 推到 SIEM

四件事任一缺失、就是 Audit Log 與 Secret Management 邊界的待補項目。

日常操作與決策形狀

IAM Conditions 收 scope：GSM 的 secretAccessor role 預設綁到 secret resource、但組織常見錯配是給整個 project 上 roles/secretmanager.secretAccessor — 等於整個 project 所有 secret 都能讀。應該用 per-secret binding、再加 IAM Conditions（resource.name.endsWith('prod-db-password')、request.time < timestamp('...')）限縮時間窗口。對應 Okta Cloudflare 2023 supply chain 的對照啟示：第三方 token scope 過寬時、上游事件直接傳導下游、IAM Conditions 是收 scope 的工具。

Secret Version + Alias 模型：每個 secret 有 monotonic version（v1、v2、v3…）、預設 alias latest 指向最新 enabled version。rotation 不是「更新現有 secret」、是 建立新 version + 把舊 version disable。應用端要支援 讀新 version 失敗時 fallback 舊 version、或在 rotation Cloud Function 內實作 雙軌驗證窗口（新版本上線後一段時間舊版還能讀、確認所有 consumer 切過去再 destroy 舊版）。沒這層設計、一次 rotation 就會打掉沒及時更新的 consumer。

CMEK（Customer-Managed Encryption Key）：GSM 預設用 Google-managed key、production 應該指向 Cloud KMS CMEK。意義是 把 key 持有跟 secret 取用分離 — 即使 secret admin 被攻破、沒有 CMEK 的 decrypt 權限拿不到明文。代價是 CMEK key region 跟 secret replication 要對齊（key 在 us-central1 但 secret 設 automatic replication = key 進不去其他 region、secret access 會失敗）。

Replication 策略：automatic 是 GCP 自動跨 region replicate（高可用、不需要管 region 一致性、但 data residency 受 GCP 全球策略支配）；user-managed 是手動指定 region list（精細控制資料駐留、適合有 GDPR / 跨境合規需求的場景、但 region 加減要自己管 + CMEK key 要在每個指定 region 都存在）。一個常見錯配：選 user-managed 但只設一個 region — 等於沒有跨 region 冗餘、該 region 出事 secret 完全讀不到。

Rotation 是自管 schedule：GSM 提供的不是 rotation logic、是 Rotation Schedule（cron 或固定間隔）、到期會發 Pub/Sub message 到指定 topic、由 自己寫的 Cloud Function / Cloud Run 訂閱該 topic 執行實際 rotation（呼叫上游系統 API 生新 credential、寫成新 secret version、disable 舊 version）。對應 Failure: Credential Rotation Without Scope：rotation Cloud Function 必須自己處理 scope map（哪些 consumer 用了同一把 secret）跟 雙軌驗證窗口（confirm 所有 consumer 切到新版本才 disable 舊版）、不像 AWS Secrets Manager 有 built-in 四階段 flow（createSecret → setSecret → testSecret → finishSecret）。

Workload Identity Federation 取用：external workload（GitHub Actions / AWS workload / Azure workload / on-prem K8s）用 WIF 拿 GSM secret 是現代預設模式 — workload 用自己的 OIDC token（GitHub OIDC、AWS STS）跟 GCP STS 交換 short-lived access token、再用 token 呼叫 GSM。避開了「長期 service account JSON key 散落 CI / 第三方環境」的問題。GKE 內 workload 走 GKE Workload Identity（pod ServiceAccount → GCP service account 綁定）取 secret、也是同 mindset。

Audit log 治理：GSM 的 audit 分兩層 — Admin Activity（create / delete / IAM 變更、預設開、免費）、Data Access（AccessSecretVersion、預設 關、開啟有 log 量跟 BigQuery export cost）。production 不開 Data Access = 事故時 連 secret 被誰取過都查不到、必須在 project IAM Audit Config 開、Cloud Logging sink 推到 SIEM 或 BigQuery（見 7.13 偵測覆蓋率與訊號治理）。

核心取捨表

選 GSM 的核心訴求：workload 主要跑在 GCP（GKE / Cloud Run / Cloud Build）、已經用 Workload Identity Federation 收 service account key、secret 形態以 static 為主（DB password、third-party API key、private key）、rotation 邏輯願意用 Cloud Function 自寫。要跨雲、要 dynamic credential、要內建 rotation flow、需要 transit encryption — 走 Vault。

進階主題

CMEK + Cloud KMS 雙軌權限分離：production 應該 至少 把 prod secret 的 CMEK key 跟 secret IAM 分到不同 admin group — secret admin 可以建 / 改 secret 但不能 decrypt（沒 KMS cloudkms.cryptoKeyDecrypter），KMS admin 可以管 key 但不能讀 secret 內容。對應 Microsoft Storm-0558 signing key chain 的對照啟示：key 不離 KMS 邊界、跟 HSM-bound 同 mindset；CMEK 是把這個原則內建到 secret 路徑。

Berglas（OSS pattern）：Berglas 是 Google 開源的 GSM client library + CLI、在 Cloud Run / Cloud Function / GKE 啟動時把 sm://... 參考自動 resolve 成實際 secret value、注進環境變數或檔案。比起應用端寫 SDK 取 secret 的好處：secret 不進 container image / build manifest、只有 runtime 取得；缺點是多一層 dependency、且 Berglas 自己有 IAM 需求要管。

GKE Workload Identity 取用：GKE pod 用 ServiceAccount → IAM service account 綁定（透過 iam.gke.io/gcp-service-account annotation）、pod 內呼叫 GSM API 自動帶 GCP service account 身份、metadata server 簽 token。比起把 service account JSON key mount 進 pod、Workload Identity 沒有長期 credential 在 pod 內、credential rotation 由 GCP metadata 自動處理。

Secret rotation Cloud Function 樣板：訂閱 secret 的 rotation topic（Pub/Sub）、message 帶 secret name 跟 trigger reason；Function 內呼叫上游系統 API（DB / SaaS）生新 credential、用 secretmanager.AddSecretVersion 寫新 version、等一段時間（雙軌驗證窗口）後 DisableSecretVersion 舊 version、最後 DestroySecretVersion 完成 rotation。雙軌窗口的長度必須大於 consumer 的最長 cache TTL、否則沒及時 refresh 的 consumer 會在 disable 後失敗。

Pub/Sub event subscription（new in 2023+）：除了 rotation schedule 自動發 event、GSM 也支援對 secret 任意變更（new version、IAM change）發 Pub/Sub message、可接 SOAR / SIEM 做 secret 異常變更告警（例：非 CI service account 在週末新增 secret version）。

排錯與失敗快速判讀

• 取 secret 拿到 PERMISSION_DENIED：通常是 IAM binding 在 project 層但 secret 在某 sub-resource、或 IAM Conditions 把當前 caller 排除 — 用 gcloud secrets get-iam-policy 直接看 binding、確認 condition 表達式
• CMEK 設定後突然讀不到 secret：CMEK key region 跟 secret replication region 不對齊、或 caller 沒有 KMS decrypt 權限 — 確認 key 在所有 replication region 都有版本、secret accessor service account 有 cloudkms.cryptoKeyDecrypter
• Rotation Cloud Function 跑了但 consumer 認證失敗：雙軌窗口太短或 consumer 沒實作 latest version 失敗 fallback、舊版 disable 後孤兒 consumer 直接斷 — 把雙軌窗口拉到 cache TTL × 2、補 fallback 邏輯
• Data Access audit 沒紀錄：預設關、要在 project IAM Audit Config 明確開 secretmanager.googleapis.com 的 DATA_READ — 不開等於沒辦法回答「事故當下誰讀了 secret」
• External workload 拿不到 secret：Workload Identity Federation 的 provider attribute mapping 沒對齊（GitHub OIDC token 的 repository claim 沒被 map 到 attribute condition）— 走 gcloud iam workload-identity-pools providers describe 看 mapping、用 token introspection 驗實際 claim
• Secret version 累積過多：rotation 只 disable 不 destroy、版本無限長 — 加 lifecycle policy（手動 / Cloud Function 排程）destroy 超過 N 個版本以前的舊版
• GKE pod 用 Workload Identity 但拿不到 secret：通常是 GKE 沒 enable Workload Identity feature、或 iam.gke.io/gcp-service-account annotation 拼錯、或 GCP service account 沒給 K8s ServiceAccount iam.workloadIdentityUser — 三層都要對才能通

何時改走其他服務

不在本頁內的主題

• GSM 完整 REST API 跟 gcloud secrets 詳盡子命令
• Cloud KMS key lifecycle 跟 rotation 細節（看 Google Cloud KMS 章）
• Workload Identity Federation 完整設定步驟（attribute mapping、condition expression、provider 設定看 Google Cloud IAM 章）
• Berglas 完整 CLI 用法
• Cloud Function / Cloud Run 部署細節
• GCP Organization Policy 跟 secret 跨 project 共享的進階場景

案例回寫

GSM 在 07 案例庫沒有直接 vendor-level 事件、以下案例採對照引用：

下一步路由

• 上游：7.6 秘密管理與機器憑證治理、7.13 偵測覆蓋率與訊號治理
• 平行：HashiCorp Vault、AWS Secrets Manager、Azure Key Vault
• 下游：Google Cloud KMS（GSM CMEK 後端、key custody 分離）
• 下游：Google Cloud IAM（secret IAM binding、Workload Identity Federation 設定）
• 跨模組：8 事故處理 vendor 清單（GSM 事件如何 routing 進 IR 流程）
• 官方：Secret Manager Documentation

服務定位

Azure Key Vault 的核心定位是 三合一 secret + key + cert service 加 Azure-native secret-less 取用。AWS 是 Secrets Manager + KMS + ACM 三個獨立 service、職責邊界清楚但要管三套權限；GCP 是 Google Secret Manager + Cloud KMS + Certificate Authority Service 三個獨立；Azure 把這三件事合在 Key Vault — 同一 RBAC role 可同時管 secret / key / cert、減少 IAM 維護成本、但治理上需要在 Vault 內用 naming convention + 多 Vault instance 自己劃分敏感度邊界（例：production secret / cert 分開不同 Vault、admin access 分人）。

跟 HashiCorp Vault 相比、Azure Key Vault 是 Azure-only 的 static-focused 服務 — 沒有 dynamic credential engine、沒有 transit encryption-as-a-service、沒有跨雲統一介面。優勢是 零運維 + Managed Identity 取用免 client secret + Premium tier 直接 HSM-backed。Azure-heavy + 一站式 secret/key/cert + secret-less workload 取用是 Key Vault 的甜蜜點。

本章目標

讀完本頁、讀者能判斷：

1. 哪些 secret / key / cert 適合放 Key Vault、哪些該走 Managed HSM（FIPS 140-2 Level 3 需求）
2. Access Policy 跟 Azure RBAC 兩種授權模型的差異與 migration 路徑
3. Soft Delete + Purge Protection 的 防誤刪 與 防勒索 邊界
4. 何時用 Key Vault、何時改走 HashiCorp Vault（跨雲 + dynamic credential）的取捨

最短判讀路徑

判斷 Azure Key Vault deployment 是否健康、最少看四件事：

• 誰能 access：Vault 用 Access Policy 還是 Azure RBAC、是否還有 legacy Access Policy 沒清掉、Managed Identity 的 role assignment 是否最小化（Key Vault Secrets User 而非 Key Vault Administrator）
• RBAC vs Access Policy 模型：production 應該全走 Azure RBAC（跟 Azure RBAC vendor 同套）、舊 Access Policy 是 migration backlog、不可長期兩軌並存
• Soft Delete + Purge Protection：兩個都應開、Soft Delete 90 天 retention、Purge Protection 開了之後連 owner 都不能立即 purge — 防誤刪 + 防 ransomware 一次性刪光
• Diagnostic Logs：Key Vault 預設不記操作 log、必須手動配 Diagnostic Setting 推 Log Analytics / Event Hub / Storage — 沒這層 KeyVaultGet / SecretGet 都沒 audit trail

四件事任一缺失、就是 Audit Log 與 Secret Management 邊界的待補項目。

日常操作與決策形狀

Vault Standard vs Premium：Standard 用 software protection（key 存在 Microsoft-managed software boundary）、Premium 用 FIPS 140-2 Level 2 HSM-backed key、key material 在 HSM 內、不可 export。Premium 適合 signing key / wrapping key 等高敏 key、Standard 適合 application secret + 常規 envelope encryption key。要 FIPS 140-2 Level 3、Standard 跟 Premium 都不夠、必須用 Managed HSM。

Access Policy vs Azure RBAC（兩種授權）：Access Policy 是 Key Vault legacy 模型 — 在 Vault 物件上掛一張 capability 表（Get / List / Set / Delete / Encrypt / Sign 等細粒度權限）、跟 Azure RBAC 體系獨立。Azure RBAC 模型是新版 — 用 Azure built-in role（Key Vault Secrets User / Key Vault Crypto User / Key Vault Administrator）走 Entra ID 統一身份治理。production 全走 RBAC、舊 Vault 的 Access Policy 是 migration backlog — 兩軌並存會出現 RBAC 拒絕但 Access Policy 允許 的權限漏洞。

Managed Identity 取用（secret-less）：Azure VM / Function / App Service / AKS pod 走 Managed Identity 直接呼叫 Key Vault API — 不需要存 client secret 或 cert。Workload 拿 IMDS token、token 帶 Entra ID identity、Key Vault 端用 RBAC role assignment 驗證 — 這是 Azure-native 的 secret-less 取用模式、跟 AWS IAM Role for Service Account / GCP Workload Identity 同類設計。production 應該 只允許 Managed Identity 取用、禁用 service principal + client secret。

Secret rotation（手動 / event-driven）：Key Vault Secret 沒有像 AWS Secrets Manager 內建的 rotation Lambda。Rotation 走兩條路：手動更新 secret version（app 端拉新版）、或 Event Grid 通知 secret 過期 + Azure Function 觸發 rotation。後者需要自己寫 rotation logic、Key Vault 只提供 版本管理 跟 過期通知、不負責執行 rotation。

Key Rotation Policy：Key（不是 Secret）有 native Rotation Policy — Vault 在 key 到期前自動生成新版、舊版保留可解密但不再 encrypt。policy 設 rotationPeriod + notifyBeforeExpiry、Key Vault 自動跑、不需要外部觸發。Secret 沒這功能、Key 才有。

Certificate auto-renewal：Certificate object 可整合 Issuer（DigiCert / GlobalSign / 自簽）做 auto-issue + auto-renew — Key Vault 在到期前自動跑 CSR、向 Issuer 申請新 cert、寫回同一個 Certificate object（保留歷史版本）。比起手動跑 OpenSSL + 寫進 AWS ACM、Certificate object 的優勢是 Issuer 在 Vault 端統一治理 — 不過只支援整合過的 public CA。

Soft Delete + Purge Protection：Soft Delete 預設開（2020 後新 Vault 強制開）、delete 後 90 天 retention、Recover 可救回。Purge Protection 是 額外 開關 — 開了之後 retention 內任何人（包含 subscription owner）都不能 purge 立即清除、必須等 90 天到期才會物理刪除。這是 防勒索 的關鍵 — 沒 Purge Protection、attacker 拿到 owner role 可以 delete + purge 一次性清光。

Private Endpoint：Key Vault 預設是 public endpoint（FQDN 走 internet）。Private Endpoint 把 Vault 拉進 VNet、只走內網存取 — 高敏 Vault 應該關 public access、強制走 Private Endpoint + Firewall rule（IP 白名單）。

核心取捨表

選 Azure Key Vault 的核心訴求：Azure-only、需要 secret + key + cert 一站式、workload 走 Managed Identity secret-less 取用、可接受 無 dynamic credential。需要跨雲統一 secret 控制面、或要 dynamic database credential、走 HashiCorp Vault。

進階主題

Managed HSM（dedicated）：Managed HSM 是 dedicated single-tenant HSM cluster、FIPS 140-2 Level 3、跟 multi-tenant 的 Key Vault Premium 是不同 service。Managed HSM 適合 主權合規（key material 完全自有控制權、Microsoft 也不可存取）、金融 / 醫療 / 政府場景。代價是 貴 跟 初始化要走 ceremony（多人持有 activation key、Microsoft 不可單方面操作）— 不是 Premium 的簡單升級、是另一條 product line。

Premium tier HSM-backed Key：Premium tier 的 key 有 HSM-protected 屬性、key material 在 multi-tenant HSM 內、API call 還是走標準 Key Vault endpoint、但 cryptographic operation 在 HSM 跑。比 Standard 慢一點、價格高、適合 signing key / wrapping key / root encryption key — 一般 application secret 還是 Standard 即可。

Certificate Issuer 整合：Vault 內可註冊 Issuer（DigiCert / GlobalSign / Entrust）、提供 API credential、Vault 在 Certificate 到期前自動跑 CSR、向 Issuer 申請、Issuer 簽完寫回 Vault。Self-signed / Unknown Issuer 也支援、後者表示 Vault 產 CSR、人或 pipeline 拿去外部 CA 簽完再 import 回 Vault。

Cross-tenant key access（federated identity）：Key Vault 可允許跨 Entra ID tenant 的 service principal 取用 — 透過 Federated Identity Credential（Workload Identity Federation）、外部 tenant 的 identity（甚至 GitHub Actions OIDC、AWS workload）拿 token 來 Key Vault 驗證。這是 cross-cloud workload 拉 Azure secret 的方式、不需要存 Azure service principal credential。

跟 Entra ID Conditional Access 整合：Key Vault 用 Azure RBAC 模型時、可走 Conditional Access policy — 特定 IP、已 enrolled 裝置、MFA 已驗證 才能取用 secret / key。production 高敏 Vault 應該疊 Conditional Access、避免單純 RBAC 在 token leak 時就直接被存取。

排錯與失敗快速判讀

• Diagnostic Setting 沒開：production Vault 啟用後忘了配 Diagnostic Setting 推 log、事故發生時無 SecretGet / KeyDecrypt 紀錄 — 啟動 checklist 必含「Diagnostic Setting → Log Analytics」、Azure Policy 強制全 subscription Vault 都配
• Access Policy 跟 RBAC 兩軌並存：migration 過程中 RBAC 已切換但舊 Access Policy 沒清、出現 RBAC 拒絕但 Access Policy 允許 — migration 一次切斷、跑 az keyvault update --enable-rbac-authorization true 後清空所有 Access Policy
• Soft Delete 沒開 / Purge Protection 沒開：誤刪 secret 救不回、或 attacker 拿到 owner role 一次 purge 清光 — 新 Vault 兩個都強制開、Azure Policy 阻擋 enablePurgeProtection: false 的 Vault 建立
• Managed Identity role 過寬：給 workload identity Key Vault Administrator 而非 Key Vault Secrets User — workload 拿到 admin role 等於可改 ACL — role assignment 走 least privilege built-in role
• Premium key 跑非 HSM operation：Premium key 配錯 attribute、key 變成 software-protected 而非 HSM-protected — 建 key 時明示 --protection hsm、CI 驗證 key attribute
• Certificate auto-renew Issuer credential 過期：Vault 內 DigiCert API credential 過期、auto-renew 默默失敗、cert 到期前才發現 — Issuer credential 也要 rotation + monitor
• Public access 開著：Vault 沒關 public endpoint、secret 暴露在 internet（雖然有 RBAC、但 attack surface 多一層）— 高敏 Vault 強制 Private Endpoint + Firewall rule

何時改走其他服務

不在本頁內的主題

• Key Vault REST API / Azure CLI 完整 reference
• Managed HSM activation ceremony 完整步驟
• Bicep / Terraform 配置 Key Vault 的完整 IaC 範例
• Certificate Issuer（DigiCert / GlobalSign）的合約與計價細節
• 每個 Entra ID role 的細粒度 permission map

案例回寫

下一步路由

• 上游：7.6 秘密管理與機器憑證治理、7.5 傳輸信任與憑證生命週期（Key Vault Certificate + Managed HSM 為 TLS / signing key 的 root custodian）、7.2 身分與授權邊界
• 平行（secret store）：AWS Secrets Manager、Google Secret Manager、HashiCorp Vault
• 平行（KMS-class）：AWS KMS、Google Cloud KMS、CloudHSM（Key Vault 是跨類 vendor、同時是 secret store 跟 key management）
• 下游：Azure RBAC（Managed Identity + RBAC 取用模型）
• 下游：cert-manager（K8s workload cert 自動化、可整合 Key Vault Certificate）
• 跨模組：8 事故處理 vendor 清單（Key Vault 事件如何 routing 進 IR 流程）
• 官方：Azure Key Vault Documentation

概念位置

Secret 是高風險操作能力。它們應集中放在受控系統中，並具備儲存位置、authorization、使用範圍、輪替週期、撤銷流程與 audit log。

可觀察訊號與例子

系統需要 secret management 的訊號是服務開始連接 database、broker、雲端 API 或第三方支付。Webhook signing secret 洩漏後，攻擊者可能偽造進站事件；database 密碼洩漏後，資料存取邊界會失效。

設計責任

Secret 管理要包含 least privilege、環境隔離、輪替演練、撤銷、版本管理與部署注入方式。Runbook 應說明疑似洩漏時如何停用、輪替、追查與恢復。

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 的對照