管理安全敏感工作負載的 API 金鑰

AWS Secrets Manager 可協助您管理、擷取和輪換資料庫登入資料、應用程式登入資料、OAuth 權杖、API 金鑰，以及在其整個生命週期中的其他秘密。此頁面提供在安全敏感工作負載中管理 API 金鑰和第三方登入資料的規範指引。結合自動輪換與客戶受管 AWS KMS 金鑰和最低權限的 IAM 政策。同時設定 VPC 端點存取，將遭入侵憑證的暴露時段和爆量半徑降至最低。

在 中存放 API 金鑰 AWS Secrets Manager

本節說明如何建構 API 金鑰秘密，以獲得最佳輪換和擷取。將每個 API 金鑰儲存為具有結構化 JSON 值的個別秘密。透過此結構，您的應用程式可以擷取個別欄位，Secrets Manager 可以將正確的值傳遞至輪換函數。

下列範例顯示第三方 API 金鑰秘密的常見 JSON 結構。實際欄位取決於提供者的需求 — 檢閱提供者的文件，了解您需要存放的特定登入資料和中繼資料。

{
  "apiKey": "your-api-key-value",
  "apiKeyId": "key-identifier",
  "endpoint": "https://api.example.com/v1",
  "provider": "example-service"
}

API 金鑰的秘密結構範例

欄位	範例值	用途
apiKey	sk_live_abc123...	您的應用程式用來驗證第三方 API 的登入資料值。
apiKeyId	key_001	供應商端金鑰的識別符。在輪換期間用來建立新的金鑰和刪除舊金鑰。
endpoint	https://api.example.com/v1	API 端點 URL。使用 金鑰存放，以便擷取會傳回應用程式需要連線的所有內容。
provider	stripe	供應商名稱。適用於標記、篩選和輪換處理多個供應商的函數邏輯。

使用中繼資料標記每個秘密，以支援 IAM 政策條件和組織篩選。例如，您可以使用 AWS CLI 或 主控台，使用擁有的團隊、環境和合規範圍來標記秘密：

aws secretsmanager tag-resource \
    --secret-id prod/payments/stripe-api-key \
    --tags Key=Team,Value=payments Key=Environment,Value=production \
           Key=Provider,Value=stripe Key=Compliance,Value=pci-dss

如需建立秘密的詳細資訊，請參閱 建立 AWS Secrets Manager 秘密。

加密組態

Secrets Manager 會使用 AWS KMS 金鑰加密每個靜態秘密值。對於安全敏感工作負載，請根據您的合規和存取控制要求選擇加密金鑰。

API 金鑰秘密的 KMS 金鑰選項

Key type	使用情況	安全考量
AWS 受管金鑰 (aws/secretsmanager)	大多數工作負載的預設值。無需額外費用或金鑰管理開銷。	金鑰政策僅限於 Secrets Manager 操作，且無法修改。無法用於跨帳戶存取。
客戶自管金鑰	合規要求 （例如 PCI DSS、HIPAA、SOC 2 或其他適用標準）。跨帳戶秘密共用。金鑰用量稽核要求。	您可以控制金鑰政策。您可以限制哪些主體可以解密。您可以停用或排程與秘密無關的金鑰刪除。透過 提供獨立的稽核線索。

對於安全敏感工作負載，請使用具有下列金鑰政策條件的客戶受管金鑰：

• kms:ViaService – 將金鑰用量限制為來自 Secrets Manager () 的請求secretsmanager.<region>.amazonaws.com。

• kms:EncryptionContext:SecretARN – 透過比對 Secrets Manager 加密內容，限制對特定秘密 ARNs 的解密。

• 每個合規界限的個別金鑰 – 對不同合規範圍內的秘密使用不同的 AWS KMS 金鑰 （例如，PCI 與非 PCI 相比）。

如需加密和解密程序的完整說明，請參閱中的秘密加密和解密 AWS Secrets Manager。

API 金鑰的自動輪換

自動輪換可減少遭入侵憑證的暴露時段。Secrets Manager 會排程叫用 Lambda 函數。函數會在提供者建立新的 API 金鑰、更新秘密值，以及刪除舊金鑰。

Secrets Manager 透過受管外部秘密為某些第三方供應商提供受管輪換函數。如需此功能和支援提供者清單的詳細資訊，請參閱 受管外部秘密合作夥伴。對於沒有受管輪換支援的提供者，您可以實作自訂 Lambda 輪換函數，呼叫提供者的 API 來建立和刪除金鑰。

輪換函數生命週期

輪換 Lambda 函數會實作四個步驟。Secrets Manager 會為每個步驟叫用一次函數，並傳遞Step參數。如果任何步驟失敗，Secrets Manager 會自動重試整個輪換。

API 金鑰的輪換步驟

步驟	API 金鑰的動作	失敗處理
createSecret	呼叫提供者 API 以建立新的金鑰。使用預備標籤將新的金鑰值存放在 Secrets Manager AWSPENDING 中。	如果金鑰建立失敗，輪換不會繼續進行下一個步驟。現有金鑰會保持作用中狀態為 AWSCURRENT。
setSecret	對於在提供者建立的 API 金鑰，此步驟通常是無操作。此步驟會在 Secrets Manager 中產生隨機金鑰，且需要在提供者處設定時使用，這不是典型的 API 金鑰流程。	如果此步驟失敗，輪換不會繼續進行 testSecret。
testSecret	從 Secrets Manager 擷取AWSPENDING值，並對提供者進行測試 API 呼叫，以驗證新金鑰是否正常運作。	如果測試失敗，請刪除供應商的待處理金鑰並引發例外狀況。
finishSecret	AWSCURRENT 移至新金鑰。舊金鑰會移至 AWSPREVIOUS。選擇性地刪除提供者的舊金鑰。	如果標籤更新失敗，輪換不會完成。新金鑰存在，但尚未標記 AWSCURRENT。

如需完整的輪換函數範本和實作指引，請參閱 Lambda 輪換函數。

輪換排程組態

根據您的合規要求和內部安全政策設定輪換間隔。請參閱工作負載適用的合規標準，以判斷適當的輪換頻率。

使用輪換時段來控制輪換發生的時間。這可防止在尖峰流量或維護時段期間輪換執行：

aws secretsmanager rotate-secret \
    --secret-id prod/payments/stripe-api-key \
    --rotation-rules '{
        "ScheduleExpression": "cron(0 4 ? * SUN *)",
        "Duration": "2h"
    }'

如需排程表達式語法，請參閱 輪換排程。

有效率地擷取秘密

Secrets Manager 每秒支援 10，000 GetSecretValue筆通話交易。大多數應用程式不會遇到限流。對於具有極高呼叫量或延遲敏感路徑的應用程式，請使用快取解決方案來減少 API 呼叫並改善回應時間。

Secrets Manager 提供數種語言的快取用戶端，以及可在執行環境中本機快取秘密的 Lambda 擴充功能。如需快取選項的詳細資訊，請參閱 使用 Java 搭配用戶端快取取得 Secrets Manager 秘密值、 使用 Python 搭配用戶端快取取得 Secrets Manager 秘密值和 使用 Go 搭配用戶端快取取得 Secrets Manager 秘密值。

針對所有存取模式，設定 IAM 政策，以限制每個應用程式所需的secretsmanager:GetSecretValue特定秘密：

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "secretsmanager:GetSecretValue",
    "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/payments/*",
    "Condition": {
      "StringEquals": {
        "aws:ResourceTag/Environment": "production"
      }
    }
  }]
}

敏感工作負載的安全強化

下列實務在具有嚴格安全要求的環境中 （例如 PCI DSS、SOC 2、HIPAA 或其他適用的合規架構），提供 API 金鑰的深度防禦：

使用 VPC 端點限制網路存取

為 Secrets Manager 建立介面 VPC 端點，以便秘密擷取永遠不會周遊公有網際網路。套用端點政策，限制可透過端點存取哪些秘密。如需詳細資訊，請參閱使用 AWS Secrets Manager VPC 端點。

將資源政策套用至秘密

將資源政策連接到每個秘密，該秘密明確拒絕來自您帳戶外部或特定 VPC 端點外部的委託人存取。這提供第二個獨立於 IAM 身分政策的授權界限。

使用 監控秘密存取

會自動記錄所有 Secrets Manager API 呼叫，包括 GetSecretValue、 PutSecretValue和 RotateSecret。對於安全敏感秘密，請建立 Amazon CloudWatch 警示，在未預期的GetSecretValue呼叫時觸發 - 例如，來自無法辨識來源 IP 地址或 IAM 主體的呼叫。

使用 AWSPREVIOUS 進行正常輪換

在輪換期間，Secrets Manager AWSPREVIOUS 會使用預備標籤維護先前的金鑰值。如果您的供應商在建立新金鑰時使上一個金鑰失效，請將您的應用程式設定為在 AWSCURRENT傳回身分驗證錯誤AWSPREVIOUS時回復為 。這可防止金鑰建立和標籤更新之間的短暫時段停機。

在連接之前驗證資源政策

沒有資源政策的秘密已封鎖公開存取。當您將資源政策連接到秘密時，請使用 ValidateResourcePolicy API 來確保您的政策不會授予廣泛的公開存取。您也可以搭配 使用 BlockPublicPolicy 參數PutResourcePolicy，以防止連接授予公有存取權的政策。在資源政策中使用 aws:PrincipalOrgID條件索引鍵，以防止來自組織外部主體的存取。

常見問答集

本節回答有關 API 金鑰輪換和秘密管理的常見問題 AWS Secrets Manager。

如何在輪換期間處理重疊期間？

只有在供應商在建立新金鑰時使現有金鑰失效時，才需要這樣做。如果提供者同時支援多個作用中金鑰，這兩個金鑰會在輪換期間運作，而不需要應用程式端備用邏輯。對於使舊金鑰失效的提供者，AWSPREVIOUS如果目前的金鑰傳回 401 或 403 錯誤，請將您的應用程式設定為使用 重試。只有在您確認新金鑰正常運作後，才能在 finishSecret 步驟中刪除提供者的舊金鑰。

如果我的提供者不支援建立程式設計金鑰，該怎麼辦？

如果提供者需要手動建立金鑰 （例如透過 Web 主控台），您就無法完全自動化輪換。反之，請使用輪換函數，在輪換到期時傳送通知 （透過 Amazon Simple Notification Service)，提示運算子手動建立金鑰並更新秘密值。設定輪換排程以符合您的合規輪換需求，並在 上使用 Amazon CloudWatch 警示days_since_last_rotation來偵測遺漏的輪換。

擷取秘密時如何避免 API 限流？

Secrets Manager 在 上支援每秒 10，000 筆交易GetSecretValue。大多數應用程式不會遇到限流。如果您的應用程式發出非常大量的呼叫，請使用快取用戶端或 Lambda 參數和秘密延伸。這些會快取記憶體中的秘密值並定期重新整理，減少 API 呼叫的數量。將快取 TTL 設定為比輪換間隔短的值，讓應用程式在輪換後挑選新的金鑰。

我應該在每個環境使用一個秘密，還是使用一個具有 版本的秘密？

為每個環境使用個別的秘密 （例如 prod/payments/stripe和 dev/payments/stripe)。這允許每個環境不同的 IAM 政策、輪換排程和加密金鑰。秘密版本 （預備標籤） 用於輪換狀態管理，而非環境分離。