JWT 検証のトラブルシューティング

OpenAPI   |  gRPC

クライアント アプリケーションから API へのリクエストに JSON ウェブトークン（JWT）が含まれている場合、Extensible Service Proxy（ESP）はそのリクエストを API バックエンドに送信する前に JWT を検証します。ここでは、JWT 検証で不合格になり、クライアントへのレスポンスでエラーが返される場合のトラブルシューティング情報を説明します。JWT の詳細については、RFC7519 をご覧ください。

エラー: 401: Jwt issuer is not configured

これは、Cloud Run で ESPv2 をデプロイする際、gcloud run deploy コマンドでフラグ --allow-unauthenticated が使用されない場合に発生する可能性があります。このフラグを使用しない場合、ESPv2 ではなく、Cloud Run の <a=" docs="" managing-access"="" run="" securing=""> アクセス制御 IAM サーバーによって、JWT トークンがインターセプトおよび検証されます。IAM は ESPv2 とは異なる発行元を使用できます。</a=">

エラー: BAD_FORMAT

以下をご確認ください。

• JWT に有効な JSON が含まれていることを確認します。
• JWT ヘッダーに "alg" フィールドがあり、"RS256"、"HS256"、"RS384"、"HS384"、"RS512"、"HS512" のいずれかに設定されていることを確認します。
• JWT ペイロード内の以下のフィールド（存在する場合）のデータ型が以下のようになっていることを確認します。
• "iat"（issued at）、"exp"（expiration time）、"nbf"（not before）の各クレームが 0 より大きい数値であり、文字列ではない。
• "sub"（subject）、"iss"（issuer）、"jti"（JWT ID）の各フィールドが文字列である。
• "aud"（audience）クレームが、文字列、または文字の配列である。
• "sub"（subject）、"iss"（issuer）、"aud"（audience）の各クレームが JWT ペイロードに存在することを確認します。

有効な、デコードされた JWT トークンの例を次に示します。

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "42ba1e234ac91ffca687a5b5b3d0ca2d7ce0fc0a"
}

Payload:
{
  "iss": "[e-mail]",
  "iat": 1493833746,
  "aud": "myservice.appspot.com",
  "exp": 1493837346,
  "sub": "[e-mail]"
}

エラー: TIME_CONSTRAINT_FAILURE

jwt.io を使って JWT をデコードし、以下のようになっていることを確認します。

• "exp"（expiration time）クレームが存在する。
• "exp"（expiration time）クレーム値は未来の日時になっている。現在の日時は、"exp" クレームにリストされている期限切れ日時よりも前の日時になっている必要があります。
• "nbf"（not before）クレームが存在する場合、過去の日時である。現在の日時は、"nbf" クレームにリストされている日時以降の日時になっている必要があります。

エラー: UNKNOWN

jwt.io を使用して JWT をデコードし、以下を確認します。

• "iss"（issuer）クレームがメールアドレスである場合、"sub"（subject）と "iss" クレームが同じである。 これは、メール発行者が JWT を自己発行したことを保証するためです。

エラー: KEY_RETRIEVAL_ERROR

• OpenAPI ドキュメントの x-google-jwks_uri フィールドで指定された公開鍵 URI が正しく、有効であることを確認します。

エラー: Issuer not allowed

• JWT トークン内の "iss"（issuer）クレームが、OpenAPI ドキュメントのセキュリティ オブジェクトの securityDefinitions セクションにある x-google-issuer フィールドに設定されている値と一致することを確認します。

• OpenAPI ドキュメントで、呼び出される API メソッドに関するセキュリティ オブジェクトが有効になっていることを確認します。

securityDefinition オブジェクトと security オブジェクトを使用してメソッドレベルでセキュリティを記述する方法の例については、サンプル openapi.yaml ファイルをご覧ください。

エラー: Audience not allowed

JWT トークン内の "aud"（audience）クレームを比較して、（OpenAPI ドキュメントの host フィールドに対応する）Endpoints サービス名と一致するかどうかを確認します。

"aud" クレームと Endpoints サービス名が異なる場合は、次のようにします。

• JWT の "aud" クレームが、OpenAPI ドキュメントで指定された x-google-audiences 値のいずれかの値と一致することを確認します。

• x-google-audiences と x-google-issuer が OpenAPI ドキュメントの同じ securityDefinitions オブジェクトにあることを確認します。

"aud" クレームと Endpoints サービス名が同じである場合、ESP によってオーディエンス（対象）が検証され、OpenAPI ドキュメントの x-google-audiences の値は無視されます。たとえばサービス名が "myservice.endpoints.example-project-12345.cloud.goog" である場合、"aud" が "myservice.endpoints.example-project-12345.cloud.goog" または "https://myservice.endpoints.example-project-12345.cloud.goog" に設定されている JWT は有効なオーディエンスです。