为 HTTP API 配置双向 TLS 身份验证 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

为 HTTP API 配置双向 TLS 身份验证

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

要为 HTTP API 启用双向 TLS,您必须为 API 配置自定义域名。您可以为自定义域名启用双向 TLS,然后向客户端提供自定义域名。要使用启用了双向 TLS 的自定义域名访问 API,客户端必须提供您在 API 请求中信任的证书。

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

重要

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

为自定义域名配置双向 TLS

要使用双向 TLS,请创建您信任的 X.509 证书的信任存储库以访问您的 API。证书可以来自公有或私有证书颁发机构。证书的最大链长度可为四。您还可以提供自签名证书。支持以下:

  • SHA-256 或更强

  • RSA-2048 或更强

  • ECDSA-256 或更强

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

验证 说明

X.509 语法

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

完整性

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

有效性

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

名称链接/键链接

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

以单个文件将信任存储库上传到 Amazon S3 存储桶。

例 certificates.pem

-----BEGIN CERTIFICATE----- <Certificate contents> -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- <Certificate contents> -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- <Certificate contents> -----END CERTIFICATE----- ...

以下 Amazon CLI 命令会将 certificates.pem 上传到 Amazon S3。

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

将信任存储库上传到 Amazon S3 后,您可以将自定义域名配置为使用双向 TLS。

当您创建已启用双向 TLS 的自定义域名或更新自定义域以使用新的信任存储库时,如果信任存储库中的证书无效,则 API Gateway 返回警告。仍然启用双向 TLS,但某些客户端可能无法访问您的 API。要解决警告,请将新的信任存储库上传到 S3,然后更新您的域名以使用新版本。有关更多信息,请参阅 排查证书警告问题

注意

要启用相互 TLS,域名必须使用由 颁发的公开信任的服务器证书Amazon Certificate Manager

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 请求中提供受信任证书。以下示例 curl 命令将请求发送到在请求中包含 api.example.com,my-cert.pemmy-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 不会通知您。

以下 Amazon CLI 命令将自定义域名更新为使用新的信任存储库版本。

aws apigatewayv2 update-domain-name \ --domain-name api.example.com \ --mutual-tls-authentication truststoreVersion='abcdef123'

禁用双向 TLS

要为自定义域名禁用双向 TLS,请从自定义域名中删除信任存储库,如以下命令所示。

aws apigatewayv2 update-domain-name \ --domain-name api.example.com \ --mutual-tls-authentication truststoreUri=''

排查证书警告问题

当您创建已启用双向 TLS 的自定义域名或更新自定义域以使用新的信任存储库时,如果证书无效,则 API Gateway 返回警告。警告指示证书存在问题以及生成警告的证书的主题。

要标识生成警告的证书,请解码信任存储库中的证书。您可以使用诸如 openssl 等工具对证书进行解码和标识其主题。

以下命令显示证书的内容,包括其主题。

openssl x509 -in certificate.crt -text -noout

更新或删除生成警告的证书,然后将新的信任存储库版本上传到 Amazon S3。将新的信任存储库上传到 Amazon S3 后,请更新您的自定义域名以使用新的信任存储库。