JWT / authentication error guide

JWTの認証エラーを、期限・対象・署名に分けて確認する

decodeしたpayloadを認証済みと誤解しないよう、exp・issuer・audience・署名・構文の境界を一つずつ見ます。

decodeと認証を分ける

headerとpayloadが読めても、署名が正しいとは限りません。署名検証にはサービスが信頼する鍵・アルゴリズム設定が必要で、issuerとaudienceも受け側の契約と照合します。

header.payload.signature
exp / iat  → 時間の主張
iss         → 発行者の契約
aud         → 対象サービスの契約
	signature   → decodeとは別の検証

境界	確認すること
`exp` / `iat`	期限切れ・未来の発行時刻を、署名検証とは別に確認する。
`iss`	発行者が受け側の許可したissuerと一致するか確認する。
`aud`	tokenの対象が、そのサービスのaudience契約と一致するか確認する。
署名	未検証のdecode結果は認証材料にしない。JWKS取得や鍵推測を行わない。
構文	3区切り・base64url・JSONの不正はfail-closedで扱う。

本番のJWT、refresh token、cookie、署名秘密鍵をこのガイドへ貼り付けないでください。サポートへ共有する場合は、fixtureや完全に無害化した例で、値の中身を確認票に含めません。

このガイドと既存のinspectorは端末内でdecodeするだけです。署名検証・JWKS・失効確認・外部送信は行いません。

case	判定	確認
`expired-or-future`	attention	exp/iatの時間だけを確認し、署名検証済みとは言わない。
`issuer-audience`	mismatch	issとaudをサービスの契約と照合する。
`signature-unverified`	reject-as-auth	decode結果を認証済みと扱わず、鍵・アルゴリズム設定の担当へ戻す。
`malformed-token`	reject	構文やJSONが不正なら成功扱いしない。

header・payload・期限の表示だけを端末内で確認する場合は既存のJWT inspectorを使います。このガイドは認証の代わりではなく、エラー分類と共有範囲の確認票です。