API Gateway で REST API の相互 TLS 認証を有効にする方法

相互 TLS 認証には、クライアントとサーバー間の双方向認証が必要です。相互 TLS では、クライアントは X.509 証明書を提示して、API にアクセスするためのアイデンティティを検証する必要があります。相互 TLS は、モノのインターネット (IoT) および B2B アプリケーションの一般的な要件です。

相互 TLS は、API Gateway がサポートする他の認可オペレーションおよび認証オペレーションと共に使用できます。API Gateway は、クライアントが提供する証明書を Lambda オーソライザーおよびバックエンド統合に転送します。

相互 TLS の前提条件

相互 TLS を設定するには、以下が必要です。

カスタムドメイン名

REST API の相互 TLS を有効にするには、API のカスタムドメイン名を設定する必要があります。カスタムドメイン名の相互 TLS を有効にした後、カスタムドメイン名をクライアントに提供できます。相互 TLS が有効なカスタムドメイン名を使用して API にアクセスするには、クライアントは API リクエストで信頼できる証明書を提示する必要があります。詳細な情報は、「API Gateway での REST API のカスタムドメイン名」にあります。

AWS Certificate Manager が発行した証明書を使用する

パブリックに信頼できる証明書は ACM から直接要求すること、またはパブリック証明書または自己署名証明書をインポートすることができます。ACM で証明書を設定するには、「ACM」を参照してください。証明書をインポートする場合は、次のセクションを参照してください。

インポートされた証明書、または AWS Private Certificate Authority 証明書を使用する

ACM にインポートされた証明書、または相互 TLS を用いた AWS Private Certificate Authority からの証明書を使用するには、API Gateway には ACM が発行した ownershipVerificationCertificate が必要です。この所有権証明書は、ドメイン名を使用する許可を持っていることを確認するためにのみ使用されます。TLS ハンドシェイクには使用されません。まだ ownershipVerificationCertificate を持っていない場合は、https://console.aws.amazon.com/acm/ に進み、その 1 つをセットアップします。

ドメイン名の有効期間中、この証明書を有効にしておく必要があります。証明書の有効期限が切れ、自動更新が失敗した場合、ドメイン名の更新はすべてロックされます。他の変更を加える前に、有効な ownershipVerificationCertificate を用いて ownershipVerificationCertificateArn を更新する必要があります。ownershipVerificationCertificate は、API Gateway の別の相互 TLS ドメインのサーバー証明書として使用できません。証明書を ACM に直接再インポートする場合、発行者は以前と同じである必要があります。

信頼ストアの設定

信頼ストアは、.pem ファイル拡張子が付いたテキストファイルです。これらは、証明機関からの証明書の信頼できるリストです。相互 TLS を使用するには、API にアクセスするために信頼する X.509 証明書の信頼ストアを作成します。

信頼ストアには、発行元の CA 証明書からルート CA 証明書までの完全な信頼チェーンを含める必要があります。API Gateway は、信頼チェーンに存在する任意の CA によって発行されたクライアント証明書を受け入れます。パブリックまたはプライベート認証機関からの証明書を使用できます。証明書チェーンの最大長は 4 です。自己署名証明書を提供することもできます。トラストストアでは、次のアルゴリズムがサポートされています。

API Gateway はいくつかの証明書プロパティを検証します。Lambda オーソライザーを使用して、証明書が失効しているかどうかのチェックなど、クライアントによる API の呼び出し時に追加のチェックを実行できます。API Gateway は、次のプロパティを検証します。

信頼ストアを 1 つのファイルで Amazon S3 バケットにアップロードします。

以下に示しているのは、.pem ファイルの具体的な例です。

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

次の AWS CLI コマンドは、certificates.pem を Amazon S3 バケットにアップロードします。

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

カスタムドメイン名の相互 TLS の設定

REST API の相互 TLS を設定するには、API のリージョン別カスタムドメイン名を TLS_1_2 セキュリティポリシーで使用する必要があります。セキュリティポリシーの選択の詳細については、「API Gateway で REST API カスタムドメインのセキュリティポリシーを選択する」を参照してください。

信頼ストアを Amazon S3 にアップロードした後、相互 TLS を使用するようにカスタムドメイン名を設定できます。次のもの（スラッシュを含む）を端末に貼り付けます。

aws apigateway create-domain-name --region us-east-2 \
    --domain-name api.example.com \
    --regional-certificate-arn arn:aws:acm:us-east-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --endpoint-configuration types=REGIONAL \
    --security-policy TLS_1_2 \
    --mutual-tls-authentication truststoreUri=s3://bucket-name/key-name

ドメイン名を作成したら、API オペレーション用に DNS レコードと基本パスのマッピングを設定する必要があります。詳細については、「API Gateway でリージョン別カスタムドメイン名を設定する」を参照してください。

相互 TLS を必要とするカスタムドメイン名を使用して API を呼び出す

相互 TLS が有効な API を呼び出すには、クライアントは API リクエストで信頼できる証明書を提示する必要があります。クライアントが API を呼び出そうとすると、API Gateway は信頼ストアでクライアント証明書の発行者を探します。API Gateway でリクエストを続行するには、証明書の発行者と、ルート CA 証明書までの完全な信頼チェーンが信頼ストアにある必要があります。

以下の例の curl コマンドは、api.example.com, が含まれるリクエストを my-cert.pem に送信します。my-key.key は証明書のプライベートキーです。

curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com

API は、信頼ストアが証明書を信頼している場合にのみ呼び出されます。次の条件により、API Gateway が TLS ハンドシェイクに失敗し、403 ステータスコードのリクエストが拒否されます。証明書が以下の場合:

信頼ストアの更新

信頼ストアの証明書を更新するには、新しい証明書バンドルを Amazon S3 にアップロードします。次に、カスタムドメイン名を更新して、更新された証明書を使用することができます。

Amazon S3 バージョニングを使用して、信頼ストアの複数のバージョンを維持します。新しい信頼ストアバージョンを使用するようにカスタムドメイン名を更新すると、証明書が無効な場合に API Gateway から警告が返されます。

API Gateway は、ドメイン名を更新するときにのみ、証明書の警告を生成します。API Gateway は、以前にアップロードされた証明書の有効期限が切れた場合でも、通知しません。

以下の AWS CLI コマンドは、新しい信頼ストアバージョンを使用するようにカスタムドメイン名を更新します。

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreVersion',value='abcdef123'

相互 TLS を無効にする

カスタムドメイン名の相互 TLS を無効にするには、以下のコマンドに示すように、カスタムドメイン名から信頼ストアを削除します。

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreUri',value=''

REST API の相互 TLS のトラブルシューティング

以下では、相互 TLS を有効にするときに発生する可能性のあるエラーや問題に関するトラブルシューティングのアドバイスを示します。

証明書の警告のトラブルシューティング

相互 TLS でカスタムドメイン名を作成する場合、信頼ストア内の証明書が有効でない場合に API Gateway から警告が返されます。これは、新しい信頼ストアを使用するようにカスタムドメイン名を更新するときにも発生します。警告は、証明書の問題と、警告の発生元となった証明書のサブジェクトを示します。相互 TLS は引き続き API で有効ですが、一部のクライアントは API にアクセスできない場合があります。

警告の発生元となった証明書を特定するには、信頼ストア内の証明書をデコードする必要があります。openssl などのツールを使用して、証明書をデコードし、そのサブジェクトを特定できます。

以下のコマンドは、証明書の内容 (サブジェクトなど) を表示します。

openssl x509 -in certificate.crt -text -noout

警告の発生元となった証明書を更新または削除してから、新しい信頼ストアを Amazon S3 にアップロードします。新しい信頼ストアをアップロードした後、その信頼ストアを使用するようにカスタムドメイン名を更新します。

ドメイン名の競合のトラブルシューティング

エラー "The certificate subject <certSubject> conflicts with an existing certificate from a different issuer." は、複数の認証機関がこのドメインの証明書を発行したことを表します。証明書の件名ごとに、相互 TLS ドメイン用の API Gateway には 1 人の発行者しか存在できません。1 つの発行者を通じて、その件名に関するすべての証明書を取得する必要があります。管理できない証明書に問題があるけれども、ドメイン名の所有権を証明できる場合は、連絡先 AWS Support からチケットを開きます。

ドメイン名のステータスメッセージのトラブルシューティング

PENDING_CERTIFICATE_REIMPORT: これは、証明書を ACM に再インポートし、検証に失敗したことを意味します。すなわち、新しい証明書には SAN (サブジェクトの別名) があり、ownershipVerificationCertificate または証明書のサブジェクトまたは SAN はドメイン名をカバーしないからです。何かが正しく設定されていないか、無効な証明書がインポートされた可能性があります。有効な証明書を ACM に再インポートする必要があります。検証の詳細については、「ドメインの所有権の検証」を参照してください。

PENDING_OWNERSHIP_VERIFICATION: 以前に検証した証明書の有効期限が切れ、ACM がそれを自動更新できなかったことを意味します。証明書を更新するか、新しい証明書をリクエストする必要があります。証明書の更新の詳細については、「ACM の管理された証明書の更新に関するトラブルシューティングガイド」を参照してください。

間違って返された証明書のトラブルシューティング

専用証明書を完全修飾ドメイン名 (FQDN) からユーザーのワイルドカードドメイン名に移行すると、API Gateway はワイルドカードドメイン名の代わりに FQDN の証明書を返す場合があります。

次のコマンドは、API Gateway から返される証明書を表示します。

openssl s_client -connect hostname:port

結果の証明書が FQDN 用である場合は、AWS Support に問い合わせてチケットを開きます。