View a markdown version of this page

在 API Gateway 中使用您自己的 ACM 憑證進行後端交互 TLS - Amazon API Gateway
先決條件步驟 1：匯入憑證，或透過 發行憑證 AWS 私有憑證授權單位步驟 2：設定 API 階段以使用 ACM 憑證步驟 3：驗證組態憑證需求憑證續約和傳播ACM 憑證行為和限制

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

在 API Gateway 中使用您自己的 ACM 憑證進行後端交互 TLS

您可以設定 API Gateway，將您自己的 CA 簽署憑證呈現給後端服務。將您的憑證匯入 AWS Certificate Manager (ACM)，或透過 發行 AWS 私有憑證授權單位。然後，將 ACM 憑證 ARN 連結至您的 API 階段。

先決條件

設定 ACM 用戶端憑證之前，您必須擁有下列項目：

  • AWS Certificate Manager 在與您 API 相同的區域中存取 。

  • IAM 許可： acm:ImportCertificate和 acm:DescribeCertificate（適用於選項 A 匯入），或 acm:RequestCertificate（適用於選項 B)acm-pca:IssueCertificate，或 acm-pca:GetCertificate、 和 acm:ImportCertificate（適用於選項 C)。

  • 部署至階段的 REST API。

步驟 1：匯入憑證，或透過 發行憑證 AWS 私有憑證授權單位

您可以從現有的 PKI 匯入憑證，或透過 發行新的憑證 AWS 私有憑證授權單位。這兩個路徑都會產生您在下列步驟中使用的 ACM 憑證 ARN。

注意

後端用戶端身分驗證不支援 ACM 公有憑證。自 2025 年 6 月 11 日起， AWS Certificate Manager 不再發行具有clientAuth擴充金鑰用量 (EKU) 的公有憑證。此功能需要 EKU，因此請使用您匯入 ACM 的憑證，或透過 發行的憑證 AWS 私有憑證授權單位。

注意

在與將使用它的 REST API 相同的 AWS 區域中建立 ACM 憑證。ACM 憑證是區域資源，因此憑證必須存在於 API 的區域中。

選項 A：從現有的 PKI 匯入

若要將用戶端憑證及其私有金鑰匯入 ACM，請執行下列命令。如需詳細資訊，請參閱 AWS Certificate Manager 使用者指南中的匯入憑證。

aws acm import-certificate \
  --certificate fileb://client-cert.pem \
  --private-key fileb://private-key.pem \
  --certificate-chain fileb://ca-chain.pem \
  --region region

命令會傳回 ACM 憑證 ARN。為下列步驟記錄此值。

選項 B：透過 AWS 私有憑證授權單位 (ACM 受管） 請求憑證

若要請求 ACM 管理且可自動續約的私有憑證，請執行下列命令。如需詳細資訊，請參閱AWS Certificate Manager 《 使用者指南》中的請求私有憑證。

aws acm request-certificate \
  --domain-name www.example.com \
  --certificate-authority-arn arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 \
  --region region

命令會傳回 ACM 憑證 ARN。為下列步驟記錄此值。

選項 C：透過 發出 AWS 私有憑證授權單位 並匯入 ACM

如果您需要直接控制憑證參數 （例如自訂延伸模組或簽署演算法），您可以透過 發行憑證， AWS 私有憑證授權單位 然後將其匯入 ACM。以這種方式匯入的憑證不會由 ACM 自動續約。確保憑證符合憑證要求。如需發行私有憑證的詳細資訊，請參閱AWS 私有憑證授權單位 《 使用者指南》中的發行私有終端實體憑證。

aws acm-pca issue-certificate \
  --certificate-authority-arn arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 \
  --csr fileb://csr.pem \
  --signing-algorithm SHA256WITHRSA \
  --validity Value=365,Type=DAYS
擷取和匯入憑證

issue-certificate 命令會傳回 AWS 私有憑證授權單位 憑證 ARN，而不是 ACM ARN。若要搭配 API Gateway 使用此憑證，請使用 擷取憑證，aws acm-pca get-certificate然後使用 將其匯入 ACMaws acm import-certificate。匯入會產生您在下列步驟中使用的 ACM 憑證 ARN。當您執行 時aws acm import-certificate，--region請將 設定為 API 的區域，以便在該處建立 ACM 憑證。

步驟 2：設定 API 階段以使用 ACM 憑證

在您擁有 ACM 憑證 ARN 之後，請設定您的 API 階段，將憑證呈現給您的後端。

設定階段 （主控台）

  1. 在 https：//https://console.aws.amazon.com/apigateway 開啟 API Gateway 主控台。

  2. 選擇您的 REST API。

  3. 選擇 Stages (階段)。

  4. 在階段詳細資訊區段中，選擇編輯。

  5. 對於用戶端憑證，請從下拉式清單中選取您的 ACM 憑證。

  6. 選擇儲存變更。

設定階段 (AWS CLI)

執行以下命令：

aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations op='replace',path=/clientCertificateId,value=arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012
注意

API Gateway 對 ACM 和 API Gateway 產生的憑證使用相同的clientCertificateId欄位。當您提供 ACM 憑證 ARN 時，API Gateway 會自動偵測格式並使用 ACM 受管工作流程。

步驟 3：驗證組態

若要驗證 API Gateway 是否將憑證傳送至您的後端，請完成下列步驟：

後端必須請求用戶端憑證

您的後端必須設定為在 TLS 交握期間請求用戶端憑證。如果後端未請求，API Gateway 不會顯示憑證。

  1. 叫用您的 API 端點。

  2. 檢查您的後端在 TLS 交握期間取得用戶端憑證。

  3. 檢查您的後端是否接受憑證並傳回成功的回應。

如果後端拒絕憑證，請確認憑證鏈可以針對後端的信任存放區進行驗證。

憑證需求

您設定的分葉憑證必須符合下列要求。

ACM 用戶端憑證需求
需求 說明
最大鏈結長度 5 個憑證
Validity 當您設定憑證時，憑證不得過期或尚未有效
區域 ACM 憑證必須與 API 位於相同的區域
帳戶 ACM 憑證必須與 API 位於相同的帳戶中
擴充金鑰用量 (EKU) 如果存在， 必須包含 clientAuth。如果不存在，則會接受憑證。
金鑰用量 (KU) 如果存在， 必須包含 digitalSignature或 keyAgreement。如果不存在，則會接受憑證。
金鑰演算法 必須是下列其中一項：RSA 2048、RSA 3072、RSA 4096、ECDSA P-256 (EC_prime256v1)、ECDSA P-384 (EC_secp384r1) 或 ECDSA P-521 (EC_secp521r1)
ACM 憑證狀態 必須為 ISSUED
注意

API Gateway 不會驗證分葉和中繼憑證之間的信任鏈。API Gateway 也不會驗證中繼憑證的憑證意圖或基本限制條件 （例如 CA:TRUE)。您的後端會在 TLS 交握期間執行這些驗證。

憑證續約和傳播

當 ACM 中的憑證變更時，API Gateway 會偵測更新並自動傳播新憑證。您不需要重新部署階段，而且 API 在輪換期間不會發生停機時間。

憑證傳播最終一致。在更新期間，您的後端可能會收到舊憑證或新憑證，直到傳播完成為止。

憑證續約的方式取決於發行方式：

  • 透過 AWS 私有憑證授權單位 (ACM 受管） （選項 B) 發行的憑證 – ACM 會自動續約這些憑證。API Gateway 會自動偵測續約和更新。

  • 由 發行 AWS 私有憑證授權單位 和匯入的憑證 （選項 C) – ACM 不會自動續約匯入的憑證。您必須重新匯入續約的憑證。重新匯入憑證後，API Gateway 會自動偵測變更和更新。

  • 從 PKI （選項 A) 匯入的憑證 – 您必須將續約的憑證重新匯入 ACM。重新匯入憑證後，API Gateway 會自動偵測變更和更新。

ACM 透過 Amazon EventBridge 傳送憑證過期通知。您可以使用這些通知在憑證過期之前設定警示。

ACM 憑證行為和限制

檢視設定的憑證

ACM 憑證不會出現在 GetClientCertificate或 GetClientCertificates API 回應中。若要檢視在階段上設定的 ACM 憑證 ARN，請使用 GetStage。若要檢視憑證詳細資訊，請使用 ACM APIs DescribeCertificate 和 GetCertificate。

跨階段重複使用

您可以將相同的 ACM 憑證連接到多個階段。每個階段都會依其 ARN 獨立參考憑證。

用戶端憑證 APIs不適用於 ACM 憑證

ACM 憑證不是 API Gateway 管理的資源。當使用 ACM GetClientCertificate憑證 ARN 呼叫 NotFoundException時UpdateClientCertificate，、 和 DeleteClientCertificate APIs 會傳回 。使用 ACM APIs來管理憑證生命週期。

自動憑證關聯清除

當您從階段移除 ACM 憑證、更新階段以使用不同的憑證，或刪除階段或 REST API 時，API Gateway 會自動清除憑證關聯。不需要手動動作。

刪除 ACM 憑證

當 API Gateway 與其具有作用中關聯時，ACM 不允許您刪除憑證。若要從 ACM 刪除憑證，請先將其從參考憑證的所有階段中移除。