如何针对 API Gateway 中的 REST API 启用双向 TLS 身份验证 - Amazon API Gateway
使用双向 TLS 的先决条件为自定义域名配置双向 TLS使用需要双向 TLS 的自定义域名调用 API更新您的信任存储库禁用双向 TLSREST API 的双向 TLS 故障排除

如何针对 API Gateway 中的 REST API 启用双向 TLS 身份验证

双向 TLS 身份验证要求在客户端和服务器之间进行双向身份验证。使用双向 TLS，客户端必须提供 X.509 证书来验证其身份才能访问您的 API。双向 TLS 是物联网 (IoT) 和企业对企业应用程序的常见要求。

您可以使用双向 TLS 以及 API Gateway 支持的其他授权和身份验证操作。API Gateway 将客户端提供的证书转发给 Lambda 授权方和后端集成。

重要

默认情况下，客户端可以通过使用 API Gateway 为 API 生成的 execute-api 端点来调用您的 API。要确保客户端只能通过使用具有双向 TLS 的自定义域名访问您的 API，请禁用默认 execute-api 端点。要了解更多信息，请参阅“禁用 REST API 的默认端点”。

使用双向 TLS 的先决条件

要配置双向 TLS，您需要：

  • 一个区域自定义域名

  • 至少在 AWS Certificate Manager 中为您的自定义域名配置了一个证书

  • 已配置信任存储库并上载到 Amazon S3

自定义域名

要为 REST API 启用双向 TLS，您必须为 API 配置自定义域名。您可以为自定义域名启用双向 TLS，然后向客户端提供自定义域名。要使用启用了双向 TLS 的自定义域名访问 API，客户端必须提供您在 API 请求中信任的证书。您可以在 针对 API Gateway 中的 REST 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，请创建您信任的 X.509 证书的信任存储库以访问您的 API。

您必须在信任存储库中包含完整的信任链，从颁发的 CA 证书到根 CA 证书。API Gateway 接受信任链中存在的任何 CA 发布的客户端证书。证书可以来自公有或私有证书颁发机构。证书的最大链长度可为四。您还可以提供自签名证书。信任库支持以下算法：

  • SHA-256 或更强

  • RSA-2048 或更强

  • ECDSA-256 或 ECDSA-384

API Gateway 验证许多证书属性。您可以使用 Lambda 授权方在客户端调用 API 时执行其他检查，包括检查证书是否已被吊销。API Gateway 验证以下属性：

验证 说明

X.509 语法

证书必须满足 X.509 语法要求。

完整性

证书的内容不得与信任存储库中证书颁发机构签名的内容有所差异。

有效性

证书的有效期必须是最新的。

名称链接/键链接

证书的名称和主题必须形成一个完整的链条。证书的最大链长度可为四。

以单个文件的形式将信任存储库上载到 Amazon S3 存储桶

以下是 .pem 文件具体形式的示例。

例 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

要为 REST API 配置双向 TLS，必须通过 TLS_1_2 安全策略为 API 使用区域自定义域名。有关选择安全策略的更多信息，请参阅选择针对 API Gateway 中 REST API 自定义域的安全策略。

注意

私有 API 不支持双向 TLS。

将信任存储库上传到 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 Gateway 中设置区域自定义域名。

使用需要双向 TLS 的自定义域名调用 API

要调用启用了双向 TLS 的 API，客户端必须在 API 请求中提供受信任证书。当客户端尝试调用您的 API 时，API Gateway 会在您的信任存储库中查找客户端证书的发布者。为使 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 状态代码拒绝请求。如果您的证书：

  • 不可信

  • 已过期

  • 未使用支持的算法

注意

API Gateway 不验证证书是否已被吊销。

更新您的信任存储库

要更新信任存储库中的证书，请将新的证书服务包上载到 Amazon S3。然后，您可以更新自定义域名以使用更新后的证书。

使用 Amazon S3 版本控制来维护信任存储库的多个版本。当您更新自定义域名以使用新的信任存储库版本时，如果证书无效，则 API Gateway 返回警告。

API Gateway 仅在您更新域名时才生成证书警告。如果先前上传的证书过期，API Gateway 不会通知您。

以下 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=''

REST API 的双向 TLS 故障排除

以下内容为您在启用双向 TLS 时可能遇到的错误和问题提供故障排除建议。

排查证书警告问题

当使用双向 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（主题备用名称），而 ownershipVerificationCertificate 不涵盖该 SAN，或是证书中的主题或 SAN 不涵盖域名。某些内容可能配置不正确，或导入了无效的证书。您需要将有效证书重新导入 ACM。有关验证的更多信息，请参阅验证域名所有权。

PENDING_OWNERSHIP_VERIFICATION：这意味着您之前验证的证书已过期，ACM 无法自动续订。您需要续订证书或请求新证书。有关证书续订的更多信息，请查看 ACM 对托管式证书续订进行故障排除指南。

排查返回的证书不正确的问题

将专用证书从完全限定域名 (FQDN) 迁移到通配符客户端域名时，API Gateway 可能会返回 FQDN 的证书，而不是通配符域名的证书。

以下命令将显示 API Gateway 返回的证书：

openssl s_client -connect hostname:port

如果生成的证书是针对 FQDN 的，请联系 AWS Support 开具工单。