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

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

Error: 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": "myservice@myproject.iam.gserviceaccount.com",
  "iat": 1493833746,
  "aud": "myservice.appspot.com",
  "exp": 1493837346,
  "sub": "myservice@myproject.iam.gserviceaccount.com"
}
Error: TIME_CONSTRAINT_FAILURE

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

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

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

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

Error: KEY_RETRIEVAL_ERROR

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

Error: Issuer not allowed

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

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

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

Error: Audience not allowed

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

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

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

  • x-google-audiencesx-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 が有効なオーディエンス(対象)です。

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

OpenAPI を使用した Cloud Endpoints
ご不明な点がありましたら、Google のサポートページをご覧ください。