本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 管理安全敏感工作負載的 API 金鑰
<a name="api-keys-security-sensitive"></a>

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

## 在 中存放 API 金鑰 AWS Secrets Manager
<a name="api-keys-storage"></a>

本節說明如何建構 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 秘密](create_secret.md)。

## 加密組態
<a name="api-keys-encryption"></a>

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](security-encryption.md)。

## API 金鑰的自動輪換
<a name="api-keys-rotation"></a>

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

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

### 輪換函數生命週期
<a name="api-keys-rotation-function"></a>

輪換 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 輪換函數](rotate-secrets_lambda-functions.md)。

### 輪換排程組態
<a name="api-keys-rotation-schedule"></a>

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

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

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

如需排程表達式語法，請參閱 [輪換排程](rotate-secrets_schedule.md)。

## 有效率地擷取秘密
<a name="api-keys-access-patterns"></a>

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

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

針對所有存取模式，設定 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"
      }
    }
  }]
}
```

## 敏感工作負載的安全強化
<a name="api-keys-security-hardening"></a>

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

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

**將資源政策套用至秘密**  
將資源政策連接到每個秘密，該秘密明確拒絕來自您帳戶外部或特定 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`條件索引鍵，以防止來自組織外部主體的存取。

## 常見問答集
<a name="api-keys-faq"></a>

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

### 如何在輪換期間處理重疊期間？
<a name="api-keys-faq-overlap"></a>

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

### 如果我的提供者不支援建立程式設計金鑰，該怎麼辦？
<a name="api-keys-faq-not-rotating"></a>

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

### 擷取秘密時如何避免 API 限流？
<a name="api-keys-faq-throttling"></a>

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

### 我應該在每個環境使用一個秘密，還是使用一個具有 版本的秘密？
<a name="api-keys-faq-multiple-environments"></a>

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