如何在 API Gateway RESTAPIs中為 開啟相互TLS身分驗證

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

您可以使用相互TLS搭配API閘道支援的其他授權和身分驗證操作。API Gateway 會將用戶端提供的憑證轉送給 Lambda 授權方和後端整合。

相互的先決條件 TLS

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

自訂網域名稱

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

使用 AWS Certificate Manager 發行的憑證

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

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

若要使用匯入至 的憑證ACM或來自 的憑證 AWS Private Certificate Authority 搭配相互 TLS，APIGateway 需要 ownershipVerificationCertificate發行的 ACM。此擁有權憑證僅用於確認您具有使用網域名稱的許可，不會用於交TLS握。如果您還沒有 ownershipVerificationCertificate，請前往 https://console.aws.amazon.com/acm/設定。

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

設定您的信任庫

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

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

API Gateway 會驗證一些憑證屬性。當用戶端叫用 時，您可以使用 Lambda 授權方執行其他檢查API，包括檢查憑證是否已撤銷。API Gateway 會驗證下列屬性：

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

以下是可能的 .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 為自訂網域名稱設定相互

若要TLS為 REST 設定相互API，您必須使用具有APITLS_1_2安全政策的區域自訂網域名稱。如需選擇安全政策的詳細資訊，請參閱 在API閘道中為您的RESTAPI自訂網域選擇安全性原則。

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

aws apigateway create-domain-name --region us-east-2 \
    --domain-name api.example.com \
    --regional-certificate-arn arn:aws:acm:us-east-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --endpoint-configuration types=REGIONAL \
    --security-policy TLS_1_2 \
    --mutual-tls-authentication truststoreUri=s3://bucket-name/key-name

建立網域名稱之後，您必須設定API操作DNS的記錄和 Basepath 映射。如需進一步了解，請參閱 在 API Gateway 中設定區域自訂網域名稱。

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

若要叫用API已啟用互惠TLS功能的 ，用戶端必須在API請求中呈現信任的憑證。當用戶端嘗試叫用您的 時API，APIGateway 會在信任存放區中尋找用戶端憑證的發行者。若要讓 API Gateway 繼續進行請求，憑證的發行者和根 CA 憑證的完整信任鏈必須位於您的信任存放區中。

下列範例 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狀態碼的請求。如果您的憑證：

更新您的信任庫

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

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

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

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

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreVersion',value='abcdef123'

停用相互 TLS

若要停用自訂網域名稱TLS的相互關聯，請從自訂網域名稱中移除信任存放區，如下列命令所示。

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreUri',value=''

TLS 為您的 進行相互疑難排解 REST API

以下提供您在開啟相互 時可能遇到的錯誤和問題的疑難排解建議TLS。

故障診斷憑證警告

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

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

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

openssl x509 -in certificate.crt -text -noout

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

疑難排解網域名稱衝突

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

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

PENDING_CERTIFICATE_REIMPORT：這表示您將憑證重新匯入 ，ACM而且驗證失敗，因為新憑證具有 ownershipVerificationCertificate或主旨未涵蓋的 SAN（主體替代名稱），或憑證SANs中不包含網域名稱。某些項目可能設定不正確或匯入了無效的憑證。您需要將有效的憑證重新匯入 ACM。如需有關驗證的詳細資訊，請參閱驗證網域擁有權。

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

對不正確傳回的憑證進行故障診斷

將專用憑證從完整網域名稱 （FQDN） 遷移至萬用字元客戶網域名稱時，APIGateway 可能會傳回 的憑證，FQDN而非萬用字元網域名稱。

下列命令會顯示 API Gateway 正在傳回的憑證：

openssl s_client -connect hostname:port

如果產生的憑證適用於 FQDN，請聯絡 AWS Support 以開啟票證。