# API Gateway でのバックエンド相互 TLS のために、自前の ACM 証明書を使用する
API Gateway を設定して、自前の CA 署名証明書をバックエンドサービスに提示できます。証明書を AWS Certificate Manager (ACM) にインポートするか、AWS Private Certificate Authority を通じて発行します。次に、ACM 証明書 ARN を API ステージにリンクします。
## 前提条件
ACM クライアント証明書を設定する前に、以下が必要です。
+ API と同じリージョンでの AWS Certificate Manager へのアクセス。
+ IAM アクセス許可: `acm:ImportCertificate` および `acm:DescribeCertificate` (オプション A のインポートの場合)、または `acm:RequestCertificate` (オプション B の場合)、または `acm-pca:IssueCertificate`、`acm-pca:GetCertificate`、`acm:ImportCertificate` (オプション C の場合)。
+ ステージにデプロイされた REST API。
## ステップ 1: 証明書をインポートするか、AWS Private Certificate Authority を通じて発行する
既存の PKI から証明書をインポートするか、AWS Private Certificate Authority を通じて新しい証明書を発行できます。どちらの方法でも、次のステップで使用する ACM 証明書 ARN が生成されます。
**注記**
ACM パブリック証明書は、バックエンドクライアント認証のためにはサポートされていません。2025 年 6 月 11 日以降、AWS Certificate Manager は `clientAuth` 拡張キー使用法 (EKU) を使用するパブリック証明書を発行しなくなりました。本機能ではこの EKU が必要であるため、ACM にインポートする証明書、または AWS Private Certificate Authority を通じて発行された証明書を使用してください。
**注記**
これを使用する REST API と同じ AWS リージョンで ACM 証明書を作成します。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 Private Certificate Authority を通じて証明書をリクエストする (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 Private Certificate Authority を通じて発行し、ACM にインポートする
証明書パラメータ (カスタム拡張や署名アルゴリズムなど) を直接管理する必要がある場合は、AWS Private Certificate Authority を通じて証明書を発行し、ACM にインポートできます。この方法でインポートされた証明書は、ACM によって自動更新されません。証明書が[証明書要件](#rest-api-acm-client-certificates-requirements)を満たしていることを確認します。プライベート証明書の発行の詳細については、「*AWS Private Certificate Authority ユーザーガイド*」の「[プライベートエンドエンティティ証明書の発行](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` コマンドは、ACM ARN ではなく AWS Private Certificate Authority 証明書 ARN を返します。API Gateway でこの証明書を使用するには、`aws acm-pca get-certificate` を使用して証明書を取得し、`aws acm import-certificate` を使用して ACM にインポートします。インポートにより、次のステップで使用する ACM 証明書 ARN が生成されます。`aws acm import-certificate` を実行するときは、`--region` を API のリージョンに設定します。これにより、そのリージョンで ACM 証明書が作成されます。
## ステップ 2: ACM 証明書を使用するように API ステージを設定する
ACM 証明書 ARN を取得したら、API ステージを設定して証明書をバックエンドに提示します。
### ステージを設定する (コンソール)
1. API Gateway コンソール ([https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)) を開きます。
1. REST API を選択します。
1. **[Stages]** (ステージ) を選択します。
1. **[ステージの詳細]** セクションで、**[編集]** を選択します。
1. **[クライアント証明書]** で、ドロップダウンリストから ACM 証明書を選択します。
1. **[Save changes]** (変更の保存) をクリックします。
### ステージを設定するには (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 つの証明書 |
| Validity | 証明書は、設定時に有効期限が切れていたり、有効期間前であったりしてはなりません。 |
| リージョン | 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 は、リーフ証明書と中間証明書間の信頼チェーンを検証しません。また、中間証明書の証明書の目的や基本制約 (`CA:TRUE` など) も検証しません。バックエンドは、TLS ハンドシェイク中にこれらの検証を実行します。
## 証明書の更新と伝播
ACM で証明書が変更されると、API Gateway は更新を検出し、新しい証明書を自動的に伝播します。ステージを再デプロイする必要はなく、更新中に API でダウンタイムが発生することはありません。
証明書の伝播には結果的に整合性があります。更新中、伝播が完了するまでバックエンドは古い証明書または新しい証明書を受け取る場合があります。
証明書の更新方法は、その発行方法によって異なります。
+ ** AWS Private Certificate Authority を通じて発行された証明書 (ACM による管理) (オプション B)** – ACM はこれらの証明書を自動更新します。API Gateway は更新を検出し、自動的に更新します。
+ ** AWS Private Certificate Authority によって発行され、インポートされた証明書 (オプション C) ** – ACM はインポートされた証明書を自動更新しません。更新された証明書は再インポートする必要があります。証明書を再インポートすると、API Gateway は変更を検出し、自動的に更新します。
+ **PKI からインポートされた証明書 (オプション A)** – 更新した証明書は ACM に[再インポート](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html)する必要があります。証明書を再インポートすると、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 証明書の削除
ACM では、API Gateway とのアクティブな関連付けが存在する間は証明書を削除できません。ACM から証明書を削除するには、まずその証明書を参照しているすべてのステージから証明書を削除します。