本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在 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 使用者指南*中的[匯入憑證](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html)。 ``` 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 《 使用者指南*》中的[請求私有憑證](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-private.html)。 ``` 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 自動續約。確保憑證符合[憑證要求](#rest-api-acm-client-certificates-requirements)。如需發行私有憑證的詳細資訊，請參閱*AWS 私有憑證授權單位 《 使用者指南*》中的[發行私有終端實體憑證](https://docs.aws.amazon.com/privateca/latest/userguide/PcaIssueCert.html)。 ``` 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`然後使用 將其匯入 ACM`aws 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](https://console.aws.amazon.com/apigateway) 開啟 API Gateway 主控台。 1. 選擇您的 REST API。 1. 選擇 **Stages** (階段)。 1. 在**階段詳細資訊**區段中，選擇**編輯**。 1. 對於**用戶端憑證**，請從下拉式清單中選取您的 ACM 憑證。 1. 選擇**儲存變更**。 ### 設定階段 (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 端點。 1. 檢查您的後端在 TLS 交握期間取得用戶端憑證。 1. 檢查您的後端是否接受憑證並傳回成功的回應。 如果後端拒絕憑證，請確認憑證鏈可以針對後端的信任存放區進行驗證。 ## 憑證需求 您設定的分葉憑證必須符合下列要求。 **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) 匯入的憑證** – 您必須將續約的憑證[重新匯入](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html) ACM。重新匯入憑證後，API Gateway 會自動偵測變更和更新。 ACM 透過 [Amazon EventBridge](https://docs.aws.amazon.com/acm/latest/userguide/supported-events.html) 傳送憑證過期通知。您可以使用這些通知在憑證過期之前設定警示。 ## ACM 憑證行為和限制 檢視設定的憑證 ACM 憑證不會出現在 `GetClientCertificate`或 `GetClientCertificates` API 回應中。若要檢視在階段上設定的 ACM 憑證 ARN，請使用 [GetStage](https://docs.aws.amazon.com/apigateway/latest/api/API_GetStage.html)。若要檢視憑證詳細資訊，請使用 ACM APIs [DescribeCertificate](https://docs.aws.amazon.com/acm/latest/APIReference/API_DescribeCertificate.html) 和 [GetCertificate](https://docs.aws.amazon.com/acm/latest/APIReference/API_GetCertificate.html)。 跨階段重複使用 您可以將相同的 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 刪除憑證，請先將其從參考憑證的所有階段中移除。