View a markdown version of this page

API Gateway でのバックエンド相互 TLS のために、自前の ACM 証明書を使用する - Amazon API Gateway
前提条件ステップ 1: 証明書をインポートするか、AWS Private Certificate Authority を通じて発行するステップ 2: ACM 証明書を使用するように API ステージを設定するステップ 3: 設定を確認する証明書の要件証明書の更新と伝播ACM 証明書の動作と制限

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ユーザーガイドの「証明書のインポート」を参照してください。

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 ユーザーガイド」の「プライベート証明書のリクエスト」を参照してください。

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 によって自動更新されません。証明書が証明書要件を満たしていることを確認します。プライベート証明書の発行の詳細については、「AWS Private Certificate Authority ユーザーガイド」の「プライベートエンドエンティティ証明書の発行」を参照してください。

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) を開きます。

  2. REST API を選択します。

  3. [Stages] (ステージ) を選択します。

  4. [ステージの詳細] セクションで、[編集] を選択します。

  5. [クライアント証明書] で、ドロップダウンリストから ACM 証明書を選択します。

  6. [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 エンドポイントを呼び出します。

  2. TLS ハンドシェイク中にバックエンドがクライアント証明書を取得することを確認します。

  3. バックエンドが証明書を受け入れ、正常なレスポンスを返すことを確認します。

バックエンドが証明書を拒否した場合は、証明書チェーンをバックエンドのトラストストアに照らし合わせて検証できることを確認します。

証明書の要件

設定するリーフ証明書は、次の要件を満たしている必要があります。

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 に再インポートする必要があります。証明書を再インポートすると、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 証明書の削除

ACM では、API Gateway とのアクティブな関連付けが存在する間は証明書を削除できません。ACM から証明書を削除するには、まずその証明書を参照しているすべてのステージから証明書を削除します。