相互 TLS を必要とする API Gateway カスタムドメイン名からの HTTP 403 Forbidden エラーをトラブルシューティングする方法を教えてください。

簡単な説明

**注: ** API Gateway は、さまざまな理由で 403 Forbidden エラーを返します。この記事では、相互 TLS に関連する 403 Forbidden エラーのみを取り上げます。その他の種類の 403 Forbidden エラーのトラブルシューティングについては、『API Gateway からの HTTP 403 エラーをトラブルシューティングする方法を教えてください。』を参照してください。

相互 TLS を必要とするカスタムドメイン名を使用して API Gateway API を呼び出すには、クライアントは API リクエストで信頼された証明書を提示する必要があります。クライアントが API を呼び出すと、API Gateway はトラストストア内でクライアント証明書の発行元を検索します。

次の条件により、API Gateway は TLS 接続に失敗し、403 ステータスコードを返します。

• API Gateway は、トラストストアでクライアント証明書の発行元を見つけることができない。
• クライアント証明書は安全でない署名アルゴリズムを使用している。
• クライアント証明書は自己署名されている。

API で Amazon CloudWatch ログ記録が有効になっている場合、エラーの原因を示すエラーメッセージが実行ログに表示されます。

**重要: ** ログ記録を有効にしても API リクエストが CloudWatch Logs を生成しない場合、403 Forbidden エラーは相互 TLS と関係はありません。

REST API の場合

REST API に Amazon CloudWatch ログ記録を設定している場合、次のいずれかのエラーメッセージが実行ログに表示されます。

• Access denied.Reason: Could not find issuer for certificate
• Access denied.Reason: Client cert using an insecure Signature Algorithm
• Access denied.Reason: self signed certificate

HTTP API の場合

HTTP API は実行ログ記録をサポートしていません。相互 TLS を必要とし、HTTP API を呼び出すカスタムドメイン名によって返される 403 Forbidden エラーをトラブルシューティングするには、次の手順を実行します。

1. テスト目的のみで REST API を呼び出すカスタムドメイン名に、新しい API マッピングを作成してください。
   **注: ** テスト用の REST API がない場合は、PetStore REST API の例を使用してください。次に、API 例を新しいステージにデプロイし、カスタムドメイン名を使用する新しい API マッピングを作成します。
2. REST API に作成した新しい API マッピングについてはこの記事の「解決策」セクションの指示に従ってください。
3. カスタムドメイン名の API マッピングを HTTP API に再度ルーティングします。

解決策

エラーの原因を確認する

1. REST API の CloudWatch ログ記録を有効にする。

2. 実行とアクセスログ記録を設定します。**注: ** このユースケースでアクセスログ記録を設定する場合は、次の $context 変数を使用する。

   { "accountId":"$context.accountId", "apiId":"$context.apiId", "domainName":"$context.domainName", "domainPrefix":"$context.domainPrefix", "error.message":"$context.error.message", "error.responseType":"$context.error.responseType", "extendedRequestId":"$context.extendedRequestId", "httpMethod":"$context.httpMethod", "identity.sourceIp":"$context.identity.sourceIp", "identity.clientCert.clientCertPem":"$context.identity.clientCert.clientCertPem", "identity.clientCert.subjectDN":"$context.identity.clientCert.subjectDN", "identity.clientCert.issuerDN":"$context.identity.clientCert.issuerDN", "identity.clientCert.serialNumber":"$context.identity.clientCert.serialNumber", "identity.clientCert.validity.notBefore":"$context.identity.clientCert.validity.notBefore", "identity.clientCert.validity.notAfter":"$context.identity.clientCert.validity.notAfter", "identity.userAgent":"$context.identity.userAgent", "path":"$context.path", "protocol":"$context.protocol", "requestId":"$context.requestId", "requestTime":"$context.requestTime", "requestTimeEpoch":"$context.requestTimeEpoch", "resourceId":"$context.resourceId", "resourcePath":"$context.resourcePath", "stage":"$context.stage", "responseLatency":"$context.responseLatency", "responseLength":"$context.responseLength", "status":"$context.status" }

   このアクセスログテンプレートは、相互 TLS が 403 エラーの原因となる場合にクライアント証明書情報をログに記録します。また、API を呼び出そうとした呼び出し元を特定しやすくなります。

3. エラーの原因を特定するには、CloudWatch で REST API の実行ログを表示してください。相互 TLS に関連する 403 Forbidden エラーがログに記録されると、次のようなエラーメッセージが表示されます。

   Extended Request Id: {extendedRequestId} Access denied. Reason: {reason}
   ForbiddenException Forbidden: {requestId}

"Access denied.Reason: Could not find issuer for certificate" エラーを解決する

API リクエストのクライアント証明書の発行元がカスタムドメイン名のトラストストアに含まれていることを確認する

API リクエストのクライアント証明書 (client.pem) の完全な証明書チェーンが、カスタムドメイン名のトラストストアに含まれている必要があります。トラストストア (bundle.pem) は、Amazon Simple Storage Service (Amazon S3) に保存されるファイルです。クライアント証明書の発行元が必須のトラストストアに含まれているかどうかを確認するには、次の OpenSSL コマンドを実行してください。

openssl verify -CAfile bundle.pem client.pem

証明書バンドルに中間証明機関が含まれている場合は、次の OpenSSL コマンドを実行してください。

openssl verify -CAfile rootCA.pem -untrusted intCA.pem client.pem

API リクエストのクライアント証明書の発行元が必須のトラストストアに含まれている場合、コマンドは OK レスポンスを返します。

クライアント証明書の発行元が必須のトラストストアに含まれていない場合、コマンドは次のエラーを返します。

error X at Y depth lookup: unable to get local issuer certificate

このエラーを解決するには、クライアント証明書の完全な証明書チェーンを含む新しいトラストストアを Amazon S3 にアップロードしてください。

カスタムドメイン名のトラストストア内のすべてのクライアント証明書が有効であることを確認する

カスタムドメイン名のトラストストア内のクライアント証明書のいずれかが無効な場合、一部のクライアントが API にアクセスできなくなる可能性があります。トラストストア内のクライアント証明書が有効であることを確認するには、次の手順を実行します。

1. Amazon API Gateway コンソールを開く。

2. ナビゲーションペインで [Custom domain names] (カスタムドメイン名) を選択する。次に、相互 TLS を必要とするカスタムドメイン名を選択する。

3. [Domain details] (ドメインの詳細) セクションで、次のような警告がないかを確認する。 Your truststore bundle has 1 invalid certificates.

4. 上記の警告が表示された場合は、トラストストア内の証明書をデコードして、どの証明書が警告を発生させたかを特定する。次の OpenSSL コマンドは、証明書のサブジェクトと内容を表示する。

   openssl x509 -in certificate.crt -text -noout

5. 警告を生成した証明書を更新または削除する。次に、新しいトラストストアを Amazon S3 にアップロードする。

詳細については、「証明書の警告のトラブルシューティング」を参照してください。

**注: ** 証明書チェーンが保持されている場合、API Gateway はルート認証機関または任意の中間認証機関によって直接署名されたクライアント証明書を受け入れます。最後の中間認証機関のみによって署名されたクライアント証明書を検証するには、リクエストパラメータベースの AWS Lambda オーソライザーを使用してください。リクエストベースの Lambda オーソライザーでカスタム検証アルゴリズムを作成できます。クライアント証明書は、API リクエストの入力の requestContext.identity.clienCert にあります。

"Access denied.Reason: Client cert using an insecure Signature Algorithm" エラーを解決する

トラストストアのテキストファイルがサポートされているハッシュアルゴリズムを使用していることを確認してください。API Gateway は、トラストストア内で次のハッシュアルゴリズムをサポートしています。

• SHA-256 またはそれ以上
• RSA-2048 またはそれ以上
• ECDSA-256 またはそれ以上

トラストストアのテキストファイルがサポートされているハッシュアルゴリズムを使用していることを確認するには、次の OpenSSL コマンドを実行してください。

openssl x509 -in client.crt -text -noout | grep 'Signature Algorithm'

コマンドのレスポンスは、トラストストアの署名アルゴリズムを返します。アルゴリズムがサポートされていない場合は、クライアント証明書を更新してサポートされているアルゴリズムを使用してください。次に、新しいトラストストアを Amazon S3 にアップロードする。

詳細については、「信頼ストアの設定」を参照してください。

"Access denied.Reason: self signed certificate" エラーを解決する

API リクエストの自己署名クライアント証明書が変更または破損されていないことを確認してください。クライアント証明書署名リクエスト (my_client.csr)、クライアント証明書のプライベートキー (my_client.key)、およびクライアント証明書のパブリックキー (my_client.pem) は一致している必要があります。

モジュラスを比較するには、次の OpenSSL コマンドを実行します。

openssl req -noout -modulus -in my_client.csr
openssl rsa -noout -modulus -in my_client.key
openssl x509 -noout -modulus -in my_client.pem

**注: ** 比較を容易にするために短いハッシュ値を生成するには、出力モジュラスにあるパイプを使用してください。次の openssl sha1 例を参照してください。

$ openssl [operation] -noout -modulus -in [data] | openssl sha1

有効な出力例は次のようになります。

2143831a73a8bb28467860df18550c696c03fbcb
2143831a73a8bb28467860df18550c696c03fbcb
2143831a73a8bb28467860df18550c696c03fbcb

データの整合性を確認するには、コンテンツレベルでのデータ変更がないことを確認します。次の diff コマンドを実行します。

diff client.crt bundle.crt

モジュラスが一致しない場合、または diff コマンドが差分を返す場合は、クライアント証明書を再生成し、トラストストアを更新してください。次に、新しいトラストストアを Amazon S3 にアップロードします。

詳細については、「信頼ストアの設定」を参照してください。

関連情報

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