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

  • gRPC .yaml 構成ファイルの authentication: providers セクションにある jwks_uri フィールドで指定された公開鍵の URI が正しく、有効であることを確認します。

エラー: Issuer not allowed

  • JWT トークンの "iss"（issuer）クレームが、gRPC .yaml 構成ファイルの authentication: providers セクションにある issuer フィールドと一致することを確認します。

エラー: Audience not allowed

JWT トークン内の "aud"（audience）クレームが Endpoints サービス名と一致する場合、ESP はそのオーディエンスを検証し、gRPC .yaml 構成ファイル内の 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 は有効なオーディエンスです。

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

  • JWT の "aud" クレームが、gRPC .yaml 構成ファイルの authentication: providers セクションに指定されている audiences 値のいずれかと一致することを確認します。