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

クライアントアプリケーションから 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": "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

ApiIssuer アノテーションの jwksUri に指定されている公開鍵の URI が正しく、かつ有効であることを確認します。

エラー: Issuer not allowed

JWT トークン内の "iss"（issuer）クレームが ApiIssuer アノテーションの issuer に設定されている値と一致することを確認します。

エラー: Audience not allowed

JWT トークンの "aud"（audience）クレームが Endpoints サービス名と一致する場合、Cloud Endpoints Frameworks はそのオーディエンスを検証し、ApiIssuerAudience アノテーションの audiences 要素に設定された値を無視します。たとえばサービス名が "myservice.appspot.com" である場合、"aud" が "myservice.appspot.com" または "https://myservice.appspot.com" に設定されている JWT は有効なオーディエンスです。

"aud" クレームが Endpoints サービス名と同じでない場合は、以下のようにします。

JWT の "aud" クレームが ApiIssuerAudience アノテーションの audiences 要素のいずれか 1 つの値と一致することを確認します。