Debugging JSON Web Token (JWT) memerlukan pemeriksaan cermat terhadap tiga komponen utamanya: Header, Payload, dan Signature yang dipisahkan oleh titik (.). Kendala umum dalam implementasi JWT biasanya berpusat pada masalah kedaluwarsa token (expired), kesalahan kunci rahasia (secret/private key mismatch), atau algoritma enkripsi yang tidak sesuai antara klien dan peladen (server).
Untuk melakukan debugging secara efisien, Anda harus memecah string token base64URL ke bentuk aslinya, memvalidasi tanda tangan kriptografi, serta memastikan klaim waktu seperti exp (Expiration Time) dan nbf (Not Before) sudah diatur dengan benar di sistem Anda.
Struktur Anatomi JWT
Sebuah token JWT yang valid terdiri dari tiga bagian terenkode Base64Url. Tabel berikut merinci fungsi dan isi dari masing-masing bagian tersebut:
| Bagian Token | Format Enkode | Fungsi Utama & Isi Data |
|---|---|---|
| Header | Base64Url JSON | Menentukan jenis token (typ: "JWT") dan algoritma hashing yang digunakan (misal: alg: "HS256" atau RS256). |
| Payload | Base64Url JSON | Berisi klaim (claims) data pengguna, seperti ID pengguna, hak akses (roles), waktu terbit (iat), dan waktu kedaluwarsa (exp). |
| Signature | Byte Hash | Hasil enkripsi dari Header + Payload menggunakan Secret Key atau Private Key untuk memastikan token tidak dimanipulasi. |
Langkah-Langkah Teknis Debugging JWT
Ikuti prosedur sistematis berikut untuk mengidentifikasi dan memperbaiki kegagalan verifikasi JWT pada aplikasi backend atau frontend Anda:
- Salin Token Bermasalah: Ambil string JWT utuh dari header HTTP
Authorization: Bearer <token>yang dikirimkan oleh klien. - Dekode Header dan Payload: Gunakan utilitas bawaan bahasa pemrograman atau decoder online terpercaya untuk memisahkan string dan membaca klaim JSON-nya. Pastikan nilai
expbelum melewati waktu saat ini (Epoch timestamp). - Periksa Algoritma (Alg): Waspadai kerentanan eksploitasi parameter
alg: "none"atau ketidakcocokan antara algoritma simetris (HMAC) dan asimetris (RSA). Pastikan peladen secara tegas menolak algoritma yang tidak didukung. - Validasi Secret/Public Key: Uji ulang kecocokan kunci rahasia di lingkungan pengembangan (development) dan produksi (production). Pastikan variabel lingkungan (environment variables) terbaca dengan benar oleh aplikasi.
- Cek Log Peladen: Analisis jejak tumpukan error (stack trace) pada peladen untuk melihat apakah kegagalan terjadi pada tahap
jwt.verify()atau pada penolakan basis data.
Contoh Kode Dekode JWT (Node.js)
Berikut adalah cuplikan kode backend menggunakan pustaka resmi jsonwebtoken untuk melakukan verifikasi dan menangkap detail error secara spesifik saat debugging:
const jwt = require('jsonwebtoken');
function debugVerifyToken(token, secretKey) {
try {
const decoded = jwt.verify(token, secretKey);
console.log("Token Valid, Payload:", decoded);
return { success: true, data: decoded };
} catch (error) {
console.error("Gagal Debugging JWT:", error.message);
// Error umum: TokenExpiredError, JsonWebTokenError, NotBeforeError
return { success: false, error: error.name, message: error.message };
}
}
// Contoh Penggunaan
// debugVerifyToken('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', 'kunci-rahasia-anda');Tips Lapangan & Troubleshooting
Kesalahan paling sering terjadi saat debugging JWT adalah perbedaan zona waktu (timezone drift) pada peladen yang menyebabkan klaim waktu kedaluwarsa (exp) tidak sinkron. Selalu gunakan zona waktu UTC pada server aplikasi Anda. Selain itu, hindari menyimpan data sensitif seperti kata sandi atau informasi kartu kredit di dalam Payload, karena data tersebut dapat didekode oleh siapa saja yang memegang token tersebut meskipun tanda tangannya tidak bisa dipalsukan.