開発者向け作業フロー
JWT を安全にデコードする
JWT を安全にデコードする手順をまとめた実践ガイドです。JWTデコードを使い、入力確認から結果の見直しまでブラウザ内で進めます。
課題
JWT は短くログへ貼り付けやすい一方、デコードした payload にはユーザー識別子、scope、tenant ID、セッション情報、有効期限が含まれることがあります。デコードは認証問題のデバッグに役立ちますが、signature 検証やトークンを信頼してよい証明ではありません。
使う場面
- API が 401 または 403 を返し、期限、audience、scope を先に確認したいときに使います。
- ログイン後に role や権限が不足して見える場合に適しています。
- サポートケースに一部伏せられたトークンがあり、秘密ではない claim だけを確認したいときに役立ちます。
- staging のトークンは動くのに production API で失敗し、issuer、audience、tenant claim を比較したいときに使います。
- リクエストが access token、ID token、refresh 関連値を誤った場所で使っていないか確認したいときに使います。
手順
- 手順 1
機密値を先に伏せる
チケット、スクリーンショット、チャット、文書で共有する前に、実際の token 値やユーザー識別子を削除または置き換えます。
- 手順 2
トークン種類と環境を確認
トークンが development、staging、production のどこから来たか、API、ブラウザセッション、identity claim、refresh flow のどれに使うものか確認します。
- 手順 3
header と payload をデコード
ローカルでトークンを開き、algorithm、key identifier、issuer、audience、subject、expiry、scope claim を確認します。
- 手順 4
時間ベースの claim を確認
exp、nbf、iat を、失敗したリクエストに関係するクライアントまたはサーバーの時刻と比較します。
- 手順 5
信頼する前に別途検証
トークンを本物として扱う前に、アプリケーション、identity provider、backend library で signature を検証します。
- 手順 6
失敗したリクエストと claim を対応させる
デコードした audience、issuer、scope、role、tenant 識別子を、拒否された API route、環境、権限チェックと比較します。
例
JWT を安全にデコードするの例
入力
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzQyIiwic2NvcGUiOiJyZWFkOmJpbGxpbmciLCJhdWQiOiJhcGkiLCJleHAiOjE3MDAwMDAwMDB9.signature出力
{
"sub": "user_42",
"scope": "read:billing",
"aud": "api",
"exp": 1700000000
}よくあるミス
デコードを検証と混同する
JWT payload は誰でも Base64URL デコードできます。検証には信頼できる key で signature と claim を確認する必要があります。
実際の production token を共有する
Access token は実際の権限を与えることがあります。デコードした claim を投稿する前に、test token を使うか機密値を伏せてください。
Authorization ヘッダー全体を貼り付ける
Bearer の後にあるトークン値だけをコピーします。ヘッダー文字列、引用符、改行が混ざると、有効なトークンでもデコーダー上で不正な形式に見えることがあります。
未検証トークンの alg 値を信頼する
JWT ヘッダーも署名検証が終わるまではユーザー由来のデータです。デコードされた alg フィールドだけを根拠に検証方法を決めないでください。
別環境の token でデバッグする
staging token は正しくデコードできても、issuer、audience、key set、tenant、clock 設定が異なり production では失敗することがあります。
access token と ID token を混同する
ID token はサインインしたユーザーを説明し、access token は通常 API が期待する値です。claim をデコードした後、identity provider の文書でトークン種類を確認します。
よくある質問
JWT をデコードしても安全ですか？
ローカルで構造を確認する手順としては安全ですが、実際の token を共有したり signature 検証なしで claim を信頼したりしてはいけません。
トークンはデコードできるのに認証が失敗するのはなぜですか？
期限切れ、発行者の違い、別 audience 向け、必要 scope の不足、または signature 検証失敗が考えられます。
JWT デコーダーは権限を検証できますか？
デコーダーは権限に関係する claim を表示できますが、その claim がリクエストに対して有効かは backend または identity provider が判断します。
最初に確認する JWT クレームはどれですか？
まず exp、nbf、iss、aud、sub、scope、roles、tenant や organization の識別子を確認します。期限切れセッション、環境違いのトークン、権限不足の原因を説明することが多いです。
デコードしたクレームをフロントエンドの認可判断に使えますか？
デコードしたクレームはデバッグや表示上のヒントにとどめてください。実際の認可判断は、サーバー側で署名、発行者、対象、期限、scope を検証してから行う必要があります。
デコードした JWT 情報を共有する前に何を伏せるべきですか？
元の token、subject 識別子、メールアドレス、tenant ID、organization ID、session ID、内部アカウント構造が分かる custom claim を削除してください。
JWT のデコードと検証は何が違いますか？
デコードは header と payload を読むだけです。検証は信頼できる key で signature、発行者、対象、有効期限、関連ルールを確認し、トークンを受け入れるか判断します。