クライアント アプリケーションから 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
- 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 は有効なオーディエンスです。