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

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

エラー: 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"
    }
    
エラー: 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

  • endpoints.Issuer オブジェクトの第 2 パラメータで指定された公開鍵 URI が正しく、かつ有効であることを確認します。

エラー: Issuer not allowed

  • JWT トークンの "iss"(issuer)クレームが endpoints.Issuer オブジェクトの最初のパラメータと一致していることを確認します。

エラー: Audience not allowed

JWT トークンの "aud"(audience)クレームが Endpoints サービス名と一致する場合、Cloud Endpoints Frameworks はそのオーディエンスを検証し、@endpoints.api デコレータの audiences 引数に設定された値を無視します。たとえばサービス名が "myservice.appspot.com" である場合、"aud""myservice.appspot.com" または "https://myservice.appspot.com" に設定されている JWT は有効なオーディエンスです。

"aud" クレームが Endpoints サービス名と一致しない場合:

  • JWT の "aud" クレームが @endpoints.api デコレータの audiences 引数のいずれか 1 つの値と一致することを確認します。