如何RESTAPIs在API閘道中開啟相互TLS驗證

相互TLS驗證需要用戶端與伺服器之間的雙向驗證。使用相互TLS，用戶端必須出示 X.509 憑證，以驗證其身分才能存API取. 相互TLS是物聯網（IoT）和 business-to-business 應用程序的共同要求。

您可以將相互TLS配合 API Gateway 支援的其他授權和驗證作業一起使用。API閘道會將用戶端提供的憑證轉寄給 Lambda 授權者和後端整合。

相互的先決條件 TLS

要配置相互，TLS您需要：

自訂網域名稱

若要啟TLS用相互功能 RESTAPI，您必須為您的API. 您可以TLS為自訂網域名稱啟用相互作用，然後將自訂網域名稱提供給用戶端。若要使用已啟API用相互TLS啟用的自訂網域名稱來存取，用戶端必須出示您信任API要求的憑證。您可以在 API閘道RESTAPIs中的自訂網域名稱 中尋找詳細資訊。

使用 AWS Certificate Manager 核發的憑證

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

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

若要使用匯入的憑證ACM或來自相互 AWS Private Certificate Authority 的憑證TLS，API閘道需要由ownershipVerificationCertificate發行者ACM。此擁有權憑證僅用於確認您具有使用網域名稱的許可，它不用於TLS握手。如果您還沒有ownershipVerificationCertificate，請轉https://console.aws.amazon.com/acm/到設置一個。

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

設定您的信任庫

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

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

API閘道會驗證許多憑證內容。您可以使用 Lambda 授權者在用戶端呼叫時執行其他檢查API，包括檢查憑證是否已撤銷。API閘道會驗證下列內容：

請將信任庫以單一檔案的形式上傳到 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

您的 Amazon S3 儲存貯體必須具有API閘道的讀取權限，才能允許API閘道存取您的信任存放區。

TLS為自訂網域名稱設定相互作用

若要TLS為相互配置 RESTAPI，您必須使用區域自訂網域名稱與TLS_1_2安全性原則。API如需有關選擇安全性原則的詳細資訊，請參閱在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記錄和基本路徑對應。如需進一步了解，請參閱在閘道中設定地區自訂API網域名稱。

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

若要在TLS啟用相互啟用的情況下叫用，用戶端必須在API要求中顯示受信任的憑證。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 版本控制來維護多個信任庫版本。當您更新自訂網域名稱以使用新的信任庫版本時，如果憑證無效，APIGateway 會傳回警告。

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

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

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 中只能有一個發行者用於相互TLS網域。您需要透過單一發行者取得該主體的所有憑證。如果問題是您無法控制的憑證，但您可以證明您擁有網域名稱，請聯絡 AWS Support 以開啟票證。

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

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

PENDING_OWNERSHIP_VERIFICATION：這表示您之前驗證的憑證已過期，ACM無法自動續約。您將需要為憑證續約或申請新憑證。您可以在受管憑證續訂疑難排解指南中找到有關憑證續訂ACM的詳細資訊。

疑難排解傳回的憑證

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

下列指令會顯示API閘道傳回的憑證：

openssl s_client -connect hostname:port

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