View a markdown version of this page

在 API Gateway 中使用您自己的 ACM 证书实现后端双向 TLS - Amazon API Gateway
先决条件步骤 1：导入证书，或通过 AWS 私有证书颁发机构颁发证书步骤 2：将 API 阶段配置为使用 ACM 证书步骤 3：验证配置证书要求证书续订与传播ACM 证书行为和限制

在 API Gateway 中使用您自己的 ACM 证书实现后端双向 TLS

您可以将 API Gateway 配置为向后端服务出示自己的 CA 签名证书。将您的证书导入到 AWS Certificate Manager（ACM）中，或通过 AWS 私有证书颁发机构颁发证书。然后，将 ACM 证书 ARN 与 API 阶段关联。

先决条件

在配置 ACM 客户端证书之前，您必须具备以下条件：

  • AWS Certificate Manager 访问权限（在与 API 相同的区域中）。

  • IAM 权限：acm:ImportCertificate 和 acm:DescribeCertificate（用于选项 A 导入）、或 acm:RequestCertificate（用于选项 B）、或 acm-pca:IssueCertificate、acm-pca:GetCertificate 和 acm:ImportCertificate（用于选项 C）。

  • 部署到阶段的 REST API。

步骤 1：导入证书，或通过 AWS 私有证书颁发机构颁发证书

您可以从现有 PKI 中导入证书，也可以通过 AWS 私有证书颁发机构颁发新证书。这两条路径都会生成一个 ACM 证书 ARN，供您在后续步骤中使用。

注意

后端客户端身份验证不支持 ACM 公有证书。自 2025 年 6 月 11 日起，AWS Certificate Manager 不再颁发带有 clientAuth 扩展密钥用法（EKU）的公有证书。此功能需要该 EKU，因此请使用您导入到 ACM 的证书，或通过 AWS 私有证书颁发机构颁发的证书。

注意

请在与要使用 ACM 证书的 REST API 相同的 AWS 区域中创建该证书。ACM 证书是区域性资源，因此该证书必须存在于 API 所在的区域中。

选项 A：从现有 PKI 导入

要将客户端证书及其私有密钥导入到 ACM，请运行以下命令。有关更多信息，请参阅 AWS Certificate Manager 用户指南中的导入证书。

aws acm import-certificate \
  --certificate fileb://client-cert.pem \
  --private-key fileb://private-key.pem \
  --certificate-chain fileb://ca-chain.pem \
  --region region

该命令将返回 ACM 证书 ARN。请记录此值，以供后续步骤使用。

选项 B：通过 AWS 私有证书颁发机构申请证书（由 ACM 管理）

要申请 ACM 管理且可以自动续订的私有证书，请运行以下命令。有关更多信息，请参阅《AWS Certificate Manager 用户指南》中的请求私有证书。

aws acm request-certificate \
  --domain-name www.example.com \
  --certificate-authority-arn arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 \
  --region region

该命令将返回 ACM 证书 ARN。请记录此值，以供后续步骤使用。

选项 C：通过 AWS 私有证书颁发机构签发并导入到 ACM

如果您需要直接控制证书参数（例如自定义扩展或签名算法），则可以通过 AWS 私有证书颁发机构颁发证书，然后将其导入到 ACM。ACM 不会自动续订以这种方式导入的证书。确保证书符合证书要求。有关颁发私有证书的更多信息，请参阅《AWS 私有证书颁发机构 用户指南》中的颁发私有端点实体证书。

aws acm-pca issue-certificate \
  --certificate-authority-arn arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 \
  --csr fileb://csr.pem \
  --signing-algorithm SHA256WITHRSA \
  --validity Value=365,Type=DAYS
检索并导入证书

issue-certificate 命令返回 AWS 私有证书颁发机构证书 ARN，而不是 ACM ARN。要将此证书用于 API Gateway，请使用 aws acm-pca get-certificate 检索该证书，然后使用 aws acm import-certificate 将其导入到 ACM。导入会生成您在以下步骤中使用的 ACM 证书 ARN。运行 aws acm import-certificate 时，将 --region 设置为 API 所在区域，以便在该区域创建 ACM 证书。

步骤 2：将 API 阶段配置为使用 ACM 证书

获得 ACM 证书 ARN 后，请设置您的 API 阶段，以便向后端出示该证书。

配置阶段（控制台）

  1. 通过以下网址打开 API Gateway 控制台：https://console.aws.amazon.com/apigateway。

  2. 选择 REST API。

  3. 选择阶段。

  4. 在阶段详细信息部分中，选择编辑。

  5. 对于客户端证书，从下拉列表中选择您的 ACM 证书。

  6. 选择保存更改。

配置阶段（AWS CLI）

运行以下命令：

aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations op='replace',path=/clientCertificateId,value=arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012
注意

API Gateway 对 ACM 证书和 API Gateway 生成的证书使用相同的 clientCertificateId 字段。当您提供 ACM 证书 ARN 时，API Gateway 会自动检测格式并使用 ACM 托管的工作流程。

步骤 3：验证配置

要验证 API Gateway 是否将证书发送到您的后端，请完成以下步骤：

后端必须请求客户端证书

您的后端必须配置为在 TLS 握手过程中请求客户端证书。如果后端不请求证书，则 API Gateway 不会出示证书。

  1. 调用您的 API 端点。

  2. 检查您的后端是否在 TLS 握手过程中获取了客户端证书。

  3. 检查您的后端是否接受证书并返回成功的响应。

如果后端拒绝证书，请验证是否可以根据后端的信任存储对证书链进行验证。

证书要求

您配置的叶证书必须满足以下要求。

ACM 客户端证书要求
要求 说明
最大链长度 5 个证书
有效性 配置证书时，证书不得已过期或尚未生效
区域 ACM 证书必须与 API 位于同一区域中
账户 ACM 证书必须与 API 位于同一账户中
扩展密钥用法（EKU） 如果存在，则必须包含 clientAuth。如果不存在，则接受该证书。
密钥用法（KU） 如果存在，则必须包含 digitalSignature 或 keyAgreement。如果不存在，则接受该证书。
密钥算法 必须是以下证书之一：RSA 2048、RSA 3072、RSA 4096、ECDSA P-256（EC_prime256v1）、ECDSA P-384（EC_secp384r1）或 ECDSA P-521（EC_secp521r1）
ACM 证书状态 必须是 ISSUED
注意

API Gateway 不验证叶证书与中间证书之间的信任链。API Gateway 也不验证中间证书的证书意图或基本约束（例如 CA:TRUE）。您的后端在 TLS 握手过程中执行这些验证。

证书续订与传播

当 ACM 中的证书发生更改时，API Gateway 会检测到更新并自动传播新证书。您无需重新部署阶段，并且您的 API 在轮换期间不会出现停机。

证书传播是最终一致的。更新期间，在传播完成之前，您的后端可能会收到旧证书或新证书。

证书的续订方式取决于其颁发方式：

  • 通过 AWS 私有证书颁发机构颁发的证书（由 ACM 管理）（选项 B）：ACM 自动续订这些证书。API Gateway 会自动检测续订并进行更新。

  • 由 AWS 私有证书颁发机构颁发并导入的证书（选项 C）：ACM 不会自动续订导入的证书。您必须重新导入续订的证书。重新导入证书后，API Gateway 会检测到更改并自动更新。

  • 从您的 PKI 导入的证书（选项 A）：您必须将续订的证书重新导入到 ACM 中。重新导入证书后，API Gateway 会检测到更改并自动更新。

ACM 通过 Amazon EventBridge 发送证书到期通知。您可以使用这些通知在证书到期之前设置警报。

ACM 证书行为和限制

查看已配置的证书

ACM 证书不会出现在 GetClientCertificate 或 GetClientCertificates API 响应中。要查看在阶段上配置的 ACM 证书 ARN，请使用 GetStage。要查看证书详细信息，请使用 ACM API DescribeCertificate 和 GetCertificate。

跨阶段重用

您可以将相同的 ACM 证书附加到多个阶段。每个阶段都通过其 ARN 独立引用证书。

客户端证书 API 不适用于 ACM 证书

ACM 证书不是 API Gateway 托管的资源。GetClientCertificate、UpdateClientCertificate 和 DeleteClientCertificate API 在使用 ACM 证书 ARN 进行调用时返回 NotFoundException。使用 ACM API 来管理证书生命周期。

自动证书关联清理

当您从阶段中移除 ACM 证书、更新阶段以使用其它证书，或删除阶段或 REST API 时，API Gateway 会自动清理证书关联。无需手动操作。

删除 ACM 证书

当 API Gateway 与证书具有有效的关联时，ACM 不支持您删除该证书。要从 ACM 中删除证书，请先将其从所有引用该证书的阶段中移除。