在 API Gateway 中為您的 HTTP API 進行相互 TLS 驗證 - Amazon API Gateway
交互 TLS 的先決條件設定自訂網域名稱的交互 TLS使用需要交互 TLS 的自訂網域名稱叫用 API更新您的信任庫停用交互 TLS故障診斷憑證警告疑難排解網域名稱衝突疑難排解網域名稱狀態訊息

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

在 API Gateway 中為您的 HTTP API 進行相互 TLS 驗證

交互 TLS 驗證需要用戶端與伺服器之間的雙向驗證。使用交互 TLS 時，用戶端必須出示 X.509 憑證，以驗證其身分才能存取您的 API。相互 TLS 是物聯網 (IoT) 和 business-to-business 應用程式的常見需求。

交互 TLS 可與 API Gateway 支援的其他授權和身分驗證作業一起使用。API Gateway 會將用戶端提供的憑證轉送給 Lambda 授權方和後端整合系統。

重要

預設情況下，用戶端可以使用 API Gateway 為 API 產生的 execute-api 端點來叫用 API。若要確保用戶端只能透過使用具有交互 TLS 的自訂網域名稱來存取您的 API，請停用預設 execute-api 端點。如需進一步了解，請參閱停用 HTTP API 的預設端點。

交互 TLS 的先決條件

若要設定交互 TLS，您需要：

  • 自訂網域名稱

  • 至少 AWS Certificate Manager 為您的自訂網域名稱設定一個憑證

  • 已設定並上傳至 Amazon S3 的信任庫

自訂網域名稱

若要啟用 HTTP API 的交互 TLS，必須設定 API 的自訂網域名稱。您可以為自訂網域名稱啟用交互 TLS，然後將自訂網域名稱提供給用戶端。若要使用已啟用交互 TLS 的自訂網域名稱來存取 API，用戶端必須提供您在 API 要求中信任的憑證。您可以在 API Gateway 中 HTTP API 的自訂網域名稱 中尋找詳細資訊。

使用 AWS Certificate Manager 核發的憑證

您可以直接從 ACM 請求公開信任的憑證，或匯入公開或自行簽署的憑證。若要在 ACM 中設定憑證，請前往 ACM。如果想要匯入憑證，請繼續閱讀下一節。

使用匯入的或 AWS Private Certificate Authority 憑證

若要使用匯入 ACM 的憑證或來自 AWS Private Certificate Authority 相互 TLS 的憑證，API Gateway 需要 ACM 所ownershipVerificationCertificate核發的憑證。此擁有權憑證僅用於確認您具有使用網域名稱的許可，不會用於 TLS 信號交換。如果您尚未擁有 ownershipVerificationCertificate，請前往 https://console.aws.amazon.com/acm/ 以設定一個。

您需要讓此憑證在網域名稱的有效生命週期內保持有效狀態。如果憑證過期且自動續約失敗，則網域名稱的所有更新都會遭到鎖定。您需要使用有效的 ownershipVerificationCertificate 更新 ownershipVerificationCertificateArn，才能進行任何其他變更。所以，ownershipVerificationCertificate 不可作為 API Gateway 中另一個交互 TLS 網域的伺服器憑證。如果直接將憑證重新匯入至 ACM，發行者必須保持不變。

設定您的信任庫

信任庫是副檔名為 .pem 的文字檔案。它們是來自憑證授權機構的受信任憑證清單。若要使用交互 TLS，請建立信任存取 API 的 X.509 憑證的信任庫。

您必須在信任庫中包含從發行的憑證授權機構憑證到根憑證授權機構憑證完整的信任鏈。API Gateway 接受信任鏈中存在的任何憑證授權機構所發行的用戶端憑證。憑證可以來自公開或私有憑證授權單位。憑證的鏈接長度上限為四。您也可以提供自我簽署憑證。信任庫支援下列雜湊演算法：

  • SHA-256 或更強的憑證

  • RSA-2048 或更強的憑證

  • ECDSA-256 或更強的憑證

API Gateway 會驗證許多憑證屬性。當用戶端叫用 API 時，您可以透過 Lambda 授權方執行其他檢查，包括檢查憑證是否已遭撤銷。如此一來，API Gateway 就會驗證下列屬性：

驗證 描述

X.509 語法

憑證必須符合 X.509 語法需求。

完整性

憑證的內容不得從信任庫的憑證授權單位所簽署的內容進行變更。

Validity

憑證的有效期必須是最新的。

名稱鏈接/金鑰鏈接

憑證的名稱和主體必須形成一個完整的鏈接。憑證的鏈接長度上限為四。

請將信任庫以單一檔案的形式上傳到 Amazon S3 儲存貯體中

範例 certificates.pem
-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
...

下列 AWS CLI 命令會上傳certificates.pem到您的 Amazon S3 儲存貯體。

aws s3 cp certificates.pem s3://bucket-name

設定自訂網域名稱的交互 TLS

若要設定 HTTP API 的交互 TLS，您必須使用 API 的區域性自訂網域名稱，且要求的最低 TLS 版本為 1.2。如需深入瞭解如何建立和設定自訂網域名稱，請參閱在 API Gateway 中設定區域自訂網域名稱。

注意

私有 API 不支援交互 TLS。

將信任庫上傳到 Amazon S3 後，您可以將自訂網域名稱設定為使用交互 TLS。將以下內容 (包含斜線) 貼到終端機中：

aws apigatewayv2 create-domain-name \
    --domain-name api.example.com \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --mutual-tls-authentication TruststoreUri=s3://bucket-name/key-name

建立網域名稱之後，您必須設定 API 作業的 DNS 記錄和基本路徑對應。如需進一步了解，請參閱在 API Gateway 中設定區域自訂網域名稱。

使用需要交互 TLS 的自訂網域名稱叫用 API

若要叫用啟用交互 TLS 的 API，用戶端必須在 API 要求中提供受信任的憑證。當用戶端嘗試叫用您的 API 時，API Gateway 會在您的信任庫中尋找用戶端憑證的發行者。若要讓 API Gateway 繼續執行要求，憑證發行者和完整信任鏈 (一路深入到根憑證授權機構憑證) 必須位於您的信任庫中。

下列範例 curl 命令會將要求傳送至 api.example.com, 要求 my-cert.pem 中包含的要求。my-key.key 是憑證的私密金鑰。

curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com

只有在您的信任庫信任憑證時，才會叫用您的 API。下列情況會導致 API Gateway 的 TLS 信號交換失敗，並拒絕狀態碼為 403 的請求。如果您的憑證：

  • 不受信任

  • 已過期

  • 未使用支援的演算法

注意

API Gateway 並不會驗證憑證是否已遭撤銷。

更新您的信任庫

若要更新信任庫中的憑證，請將新的憑證套件上傳至 Amazon S3。之後，您可以更新自訂網域名稱，以使用更新的憑證。

您可以使用 Amazon S3 版本控制來維護多個信任庫版本。在更新自訂網域名稱以使用新的信任庫版本時，如果憑證無效，則 API Gateway 會傳回警告。

API Gateway 只會在您更新網域名稱時產生憑證警告。如果先前上傳的憑證過期，API Gateway 並不會通知您。

下列 AWS CLI 命令會更新自訂網域名稱，以使用新的信任庫版本。

aws apigatewayv2 update-domain-name \
    --domain-name api.example.com \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --mutual-tls-authentication TruststoreVersion='abcdef123'

停用交互 TLS

若要停用自訂網域名稱的交互 TLS，請從自訂網域名稱移除信任庫，如下列命令所示。

aws apigatewayv2 update-domain-name \
    --domain-name api.example.com \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --mutual-tls-authentication TruststoreUri=''

故障診斷憑證警告

建立帶有交互 TLS 的自訂網域名稱時，如果信任庫中的憑證無效，則 API Gateway 會傳回警告。在更新自訂網域名稱以使用新的信任庫時，也會發生這種情況。警告指出憑證和產生警告之憑證主體的問題。您的 API 仍然啟用交互 TLS，但有些用戶端可能無法存取您的 API。

若要識別產生警告的憑證，請解碼信任庫中的憑證。您可以使用諸如 openssl 解碼憑證及識別其主體之類的工具。

下列命令會顯示憑證的內容，包括其主體：

openssl x509 -in certificate.crt -text -noout

請更新或移除產生警告的憑證，然後將新的信任庫上傳至 Amazon S3。上傳新的信任庫之後，請更新您的自訂網域名稱以使用新的信任庫。

疑難排解網域名稱衝突

錯誤 "The certificate subject <certSubject> conflicts with an existing certificate from a different issuer." 表示多個憑證授權單位已發行此網域的憑證。對於憑證中的每個主體，交互 TLS 網域的 API Gateway 中只能有一個發行者。您需要透過單一發行者取得該主體的所有憑證。如果問題是您無法控制的憑證，但您可以證明您擁有網域名稱，請聯絡 AWS Support 以開啟票證。

疑難排解網域名稱狀態訊息

PENDING_CERTIFICATE_REIMPORT：這表示您已將憑證重新匯入至 ACM，而且由於新憑證具有 SAN (主體別名)，而且這個 SAN 不屬於 ownershipVerificationCertificate 範圍或憑證中的主體或 SAN 不包含網域名稱，導致憑證驗證失敗。某些項目可能設定不正確或匯入了無效的憑證。您需要將有效憑證重新匯入 ACM。如需有關驗證的詳細資訊，請參閱驗證網域擁有權。

PENDING_OWNERSHIP_VERIFICATION：這表示您先前驗證的憑證已過期，ACM 無法對其進行自動續約。您將需要為憑證續約或申請新憑證。關於憑證續約的詳細資訊，請參閱 ACM 的疑難排解受管憑證續約指南。