Node.jsでJWT認証：署名、検証、Expressのルート保護

JWT（JSON Web Token）は、header.payload.signature というbase64urlの3つの部分からなる文字列で、サーバーがログイン時にユーザーに渡し、その後のリクエストのたびに確認します。署名は、サーバーがトークンを発行し誰も書き換えていないことを証明しますが、ペイロードはエンコードされているだけで暗号化されていないので、誰でも読めます。Node.jsでは、jose パッケージの new SignJWT(payload).sign(secret) で作り、jwtVerify(token, secret) で確認します。

import { SignJWT, jwtVerify } from 'jose';

// In a real app the secret comes from process.env.JWT_SECRET
const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');

const token = await new SignJWT({ role: 'admin' })
    .setProtectedHeader({ alg: 'HS256' })
    .setSubject('user-42')
    .setIssuedAt()
    .setExpirationTime('1h')
    .sign(secret);

console.log(token.split('.').length, 'parts');

const { payload } = await jwtVerify(token, secret);
console.log(payload.sub, payload.role);

3 parts、続いて user-42 admin が表示されます。jwtVerify が署名と有効期限を確認して、ペイロードを返しました。jwtVerify に渡す秘密鍵を1文字変えて実行し直すと、検証は signature verification failed で失敗します。

JWTの中身

ヘッダーとペイロードはJSONで、base64urlでエンコードされています。デコードに鍵はいりません。だからJWTにパスワードなどの秘密情報を入れてはいけないのです。

import { SignJWT } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const token = await new SignJWT({ name: 'Ada', role: 'editor' })
    .setProtectedHeader({ alg: 'HS256' })
    .sign(secret);

const [header, payload, signature] = token.split('.');

console.log(Buffer.from(header, 'base64url').toString());
console.log(Buffer.from(payload, 'base64url').toString());
console.log(signature.length);

最初の2行は {"alg":"HS256"} と {"name":"Ada","role":"editor"} を表示し、トークンを持っている人なら誰でも読めます。書き換えを防いでいるのは署名（HS256なら43文字）です。editor を admin に変えると、署名が一致しなくなります。

有効期限と検証の失敗

setExpirationTime('15m') は exp クレームを書き込み、jwtVerify はそれを過ぎたトークンを拒否します。拒否はすべて code を持つエラーなので、期限切れのトークンと偽造されたトークンを区別できます。

import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const expired = await new SignJWT({ sub: 'user-42' })
    .setProtectedHeader({ alg: 'HS256' })
    .setExpirationTime(1700000000) // a moment in 2023, long past
    .sign(secret);

try {
    await jwtVerify(expired, secret);
} catch (err) {
    console.log(err.code);
}

const forged = expired.slice(0, -2) + 'xx';
try {
    await jwtVerify(forged, secret);
} catch (err) {
    console.log(err.code);
}

1つ目のチェックは ERR_JWT_EXPIRED で、署名を変えた2つ目は ERR_JWS_SIGNATURE_VERIFICATION_FAILED で失敗します。APIにとってはどちらも同じ意味（401 を返す）ですが、コードをログに残しておくとデバッグに役立ちます。

BearerトークンでExpressのルートを守る

クライアントは一度ログインしてトークンを保持し、Authorization ヘッダーで Bearer <token> として送ります。ミドルウェアがそれを検証し、ルートのためにペイロードを req.user に入れます。

// GET /me
import express from 'express';
import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const app = express();
app.use(express.json());

app.post('/login', async (req, res) => {
    const { username, password } = req.body ?? {};
    // A real app looks the user up and checks a hashed password
    if (username !== 'ada' || password !== 'lovelace') {
        return res.status(401).json({ error: 'Wrong username or password' });
    }
    const token = await new SignJWT({ name: username })
        .setProtectedHeader({ alg: 'HS256' })
        .setSubject('user-1')
        .setExpirationTime('15m')
        .sign(secret);
    res.json({ token });
});

async function requireAuth(req, res, next) {
    const header = req.get('authorization') ?? '';
    const token = header.startsWith('Bearer ') ? header.slice(7) : null;
    if (!token) return res.status(401).json({ error: 'Missing token' });
    try {
        const { payload } = await jwtVerify(token, secret);
        req.user = payload;
        next();
    } catch {
        res.status(401).json({ error: 'Invalid or expired token' });
    }
}

app.get('/me', requireAuth, (req, res) => {
    res.json({ id: req.user.sub, name: req.user.name });
});

app.listen(3000);

最初のリクエスト、トークンなしの GET /me は 401 と Missing token を受け取ります。ボディ {"username": "ada", "password": "lovelace"} で POST /login を送り、レスポンスの token をコピーしてから、ヘッダー Authorization: Bearer <token> を付けて GET /me を送り直すと、返事は {"id":"user-1","name":"ada"} になります。

jsonwebtokenパッケージ

jsonwebtoken（npm install jsonwebtoken）もよく使われる選択肢です。sign と verify はPromiseを返さず、同期的に動きます（コールバックも使えます）。

const jwt = require('jsonwebtoken');

const token = jwt.sign({ role: 'admin' }, process.env.JWT_SECRET, {
    subject: 'user-42',
    expiresIn: '1h',
});

const payload = jwt.verify(token, process.env.JWT_SECRET); // throws if invalid

新しいコードには jose を使いましょう。依存関係がなく、エッジランタイムやブラウザでも動きます。どちらのライブラリのトークンも標準のJWTなので、片方が署名したものをもう片方で検証できます。

よくある間違い

verify の代わりに decode を使う。 jwt.decode と decodeJwt は署名を確認せずにペイロードを読むので、偽造したトークンも通ってしまいます。信頼してよいのは verify が返したものだけです。

短い秘密鍵、またはコミットされた秘密鍵。 推測できるHS256の秘密鍵があると、攻撃者は自分でトークンに署名できます。ランダムな32バイト以上を使い、process.env から読み、決してコミットしないでください。

期限切れにならないトークン。 exp がないと、漏れたトークンは永遠に使えます。必ず有効期限を設定しましょう。