# 在 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 用户指南*中的[导入证书](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html)。
```
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 用户指南》**中的[请求私有证书](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-private.html)。
```
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 不会自动续订以这种方式导入的证书。确保证书符合[证书要求](#rest-api-acm-client-certificates-requirements)。有关颁发私有证书的更多信息，请参阅《AWS 私有证书颁发机构 用户指南》**中的[颁发私有端点实体证书](https://docs.aws.amazon.com/privateca/latest/userguide/PcaIssueCert.html)。
```
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](https://console.aws.amazon.com/apigateway)。
1. 选择 REST API。
1. 选择**阶段**。
1. 在**阶段详细信息**部分中，选择**编辑**。
1. 对于**客户端证书**，从下拉列表中选择您的 ACM 证书。
1. 选择**保存更改**。
### 配置阶段（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 端点。
1. 检查您的后端是否在 TLS 握手过程中获取了客户端证书。
1. 检查您的后端是否接受证书并返回成功的响应。
如果后端拒绝证书，请验证是否可以根据后端的信任存储对证书链进行验证。
## 证书要求
您配置的叶证书必须满足以下要求。
**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）**：您必须将续订的证书[重新导入](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html)到 ACM 中。重新导入证书后，API Gateway 会检测到更改并自动更新。
ACM 通过 [Amazon EventBridge](https://docs.aws.amazon.com/acm/latest/userguide/supported-events.html) 发送证书到期通知。您可以使用这些通知在证书到期之前设置警报。
## ACM 证书行为和限制
查看已配置的证书
ACM 证书不会出现在 `GetClientCertificate` 或 `GetClientCertificates` API 响应中。要查看在阶段上配置的 ACM 证书 ARN，请使用 [GetStage](https://docs.aws.amazon.com/apigateway/latest/api/API_GetStage.html)。要查看证书详细信息，请使用 ACM API [DescribeCertificate](https://docs.aws.amazon.com/acm/latest/APIReference/API_DescribeCertificate.html) 和 [GetCertificate](https://docs.aws.amazon.com/acm/latest/APIReference/API_GetCertificate.html)。
跨阶段重用
您可以将相同的 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 中删除证书，请先将其从所有引用该证书的阶段中移除。