Panduan lengkap JWT untuk developer pemula: memahami konsep, implementasi praktis di Laravel & Next.js, serta best practice keamanan autentikasi modern.

Bayangkan Anda sedang membangun aplikasi web yang membutuhkan sistem login yang aman, tetapi frustasi dengan kompleksitas penyimpanan session di server. Atau mungkin Anda ingin membuat aplikasi yang skalabel, di mana server tidak perlu mengingat status login setiap pengguna. Di sinilah JWT hadir sebagai solusi elegan yang mengubah paradigma autentikasi tradisional.

Apa Itu JWT dan Mengapa Begitu Populer?

JWT, atau JSON Web Token, adalah standar terbuka yang memungkinkan pertukaran informasi aman antara pihak-pihak sebagai objek JSON. Token ini dapat diverifikasi dan dipercaya karena ditandatangani secara digital. Jika Anda pernah menggunakan layanan seperti Google API atau Firebase, sebenarnya Anda sudah berinteraksi dengan JWT tanpa mungkin menyadarinya.

Yang membuat JWT begitu menarik bagi developer modern adalah sifatnya yang stateless. Berbeda dengan session tradisional yang mengharuskan server menyimpan status login, JWT mengandung semua informasi yang diperlukan dalam token itu sendiri. Ini berarti server tidak perlu melakukan query ke database untuk memverifikasi setiap request, sehingga mengurangi beban server dan meningkatkan skalabilitas aplikasi.

Sejarah Singkat Lahirnya JWT

Konsep JWT pertama kali diperkenalkan pada tahun 2010 melalui RFC 7519, yang disusun oleh para ahli keamanan dari berbagai perusahaan teknologi. Mereka melihat kebutuhan akan standar yang lebih sederhana dan lebih aman dibandingkan dengan metode autentikasi tradisional seperti cookie session.

Sebelum JWT menjadi populer, developer biasanya mengandalkan session-based authentication. Sistem ini bekerja dengan menyimpan identifier session di cookie browser, sementara data session lengkap disimpan di server. Meskipun berfungsi dengan baik, pendekatan ini memiliki kelemahan dalam hal skalabilitas, terutama ketika aplikasi perlu berjalan di multiple server atau microservices.

JWT muncul sebagai jawaban atas tantangan ini, menawarkan pendekatan yang lebih terdesentralisasi di mana informasi autentikasi dapat dibawa oleh client sendiri, sementara server hanya perlu memverifikasi validitas token tanpa harus menyimpan status.

Arsitektur Dasar dan Cara Kerja JWT

Untuk benar-benar memahami JWT, kita perlu membongkar struktur dasarnya. Setiap JWT terdiri dari tiga bagian yang dipisahkan oleh titik: Header, Payload, dan Signature.

Header biasanya berisi dua properti: tipe token (yang selalu "JWT") dan algoritma penandatanganan seperti HMAC SHA256 atau RSA. Bagian ini di-encode menggunakan Base64Url.

Payload adalah tempat semua "klaim" atau claims disimpan. Klaim pada dasarnya adalah pernyataan tentang entitas (biasanya user) dan data tambahan. Ada tiga jenis klaim: registered claims (seperti "iss" untuk issuer, "exp" untuk expiration time), public claims, dan private claims.

Signature adalah bagian paling krusial untuk keamanan. Signature dibuat dengan menggabungkan header yang telah di-encode, payload yang telah di-encode, sebuah secret, dan algoritma yang ditentukan di header. Signature inilah yang memverifikasi bahwa token tidak diubah-ubah selama perjalanan.

Berikut contoh visual struktur JWT:

text

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Bagian pertama (merah) adalah header, bagian kedua (ungu) adalah payload, dan bagian terakhir (biru) adalah signature.

Mengapa Dua Token? Memahami Access Token dan Refresh Token

Dalam implementasi modern, kita biasanya menggunakan dua jenis token yang bekerja sama: access token dan refresh token. Masing-masing memiliki karakteristik dan tujuan yang berbeda.

Access token adalah kunci yang membuka akses ke resource protected. Token ini memiliki masa berlaku singkat, biasanya antara 15 menit hingga 1 jam. Ketika access token kadaluarsa, aplikasi tidak bisa lagi mengakses API sampai mendapatkan token baru.

Refresh token adalah token dengan masa berlaku lebih panjang (biasanya 7-30 hari) yang digunakan khusus untuk mendapatkan access token baru. Ketika access token kadaluarsa, aplikasi dapat menggunakan refresh token untuk mendapatkan access token baru tanpa memaksa user login ulang.

Tabel perbandingan berikut memberikan gambaran jelas perbedaan kedua token ini:

Pemisahan ini menciptakan sistem keamanan berlapis. Access token yang memiliki masa berlaku pendek membatasi dampak jika token tersebut dicuri. Sementara refresh token yang disimpan dengan aman memastikan user tidak perlu login berulang kali.

Implementasi Praktis: Membangun Sistem JWT di Laravel

Mari kita terjun ke implementasi praktis dengan Laravel. Untuk memulai, kita perlu menyiapkan environment dan package yang diperlukan.

Pertama, install package JWT untuk Laravel. Package tymon/jwt-auth adalah salah satu yang paling populer dan well-maintained.

php

composer require tymon/jwt-auth

Setelah instalasi, publish konfigurasi package:

php

php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"

Kemudian generate secret key untuk menandatangani JWT:

php

php artisan jwt:secret

Sekarang, mari kita modifikasi model User untuk implement JWT:

php

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Tymon\JWTAuth\Contracts\JWTSubject;

class User extends Authenticatable implements JWTSubject
{
    // ... kode existing lainnya

    public function getJWTIdentifier()
    {
        return $this->getKey();
    }

    public function getJWTCustomClaims()
    {
        return [];
    }
}

Selanjutnya, kita buat controller untuk menangani autentikasi. Controller ini akan mengurus login, refresh token, dan logout.

php

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Str;
use App\Models\User;
use App\Models\RefreshToken;

class AuthController extends Controller
{
    public function login(Request $request)
    {
        $credentials = $request->only('email', 'password');

        if (!$token = auth()->attempt($credentials)) {
            return response()->json(['error' => 'Unauthorized'], 401);
        }

        $user = Auth::user();
        $refreshToken = $this->generateRefreshToken($user);

        return $this->issueAccessAndRefreshToken($token, $refreshToken);
    }

    private function generateRefreshToken($user)
    {
        $plainToken = Str::random(64);

        RefreshToken::create([
            'user_id' => $user->id,
            'token' => hash('sha256', $plainToken),
            'expires_at' => now()->addDays(7),
        ]);

        return $plainToken;
    }

    private function issueAccessAndRefreshToken($accessToken, $refreshToken)
    {
        return response()
            ->json([
                'access_token' => $accessToken,
                'token_type' => 'bearer',
                'expires_in' => auth()->factory()->getTTL() * 60
            ])
            ->cookie('refresh_token', $refreshToken, 60*24*7, '/', null, true, true, false, 'Strict');
    }
}

Perhatikan bahwa refresh token kita hash sebelum disimpan di database. Ini adalah praktik keamanan penting yang mencegah penyerang menggunakan token bahkan jika mereka berhasil mengakses database.

Sekarang, mari buat endpoint untuk refresh token dengan implementasi auto rotation:

php

public function refresh(Request $request)
{
    $refreshToken = $request->cookie('refresh_token');
    
    if (!$refreshToken) {
        return response()->json(['error' => 'Refresh token not found'], 401);
    }

    $hashed = hash('sha256', $refreshToken);
    $tokenRecord = RefreshToken::where('token', $hashed)->first();

    if (!$tokenRecord || $tokenRecord->expires_at->isPast()) {
        return response()->json(['error' => 'Invalid or expired refresh token'], 401);
    }

    $user = $tokenRecord->user;

    // Auto rotation: hapus token lama, buat yang baru
    $tokenRecord->delete();
    $newRefreshToken = $this->generateRefreshToken($user);
    $newAccessToken = auth()->login($user);

    return $this->issueAccessAndRefreshToken($newAccessToken, $newRefreshToken);
}

Auto rotation adalah fitur keamanan di mana setiap kali refresh token digunakan, token lama langsung dihapus dan diganti dengan token baru. Ini mencegah replay attack di mana penyerang mencoba menggunakan token yang sama berulang kali.

Terakhir, kita buat endpoint logout:

php

public function logout(Request $request)
{
    $refreshToken = $request->cookie('refresh_token');
    
    if ($refreshToken) {
        $hashed = hash('sha256', $refreshToken);
        RefreshToken::where('token', $hashed)->delete();
    }

    auth()->logout();

    return response()
        ->json(['message' => 'Successfully logged out'])
        ->cookie('refresh_token', '', -1, '/', null, true, true, false, 'Strict');
}

Pada logout, kita tidak hanya menghapus token dari database tetapi juga mengirim perintah untuk menghapus cookie di browser client.

Implementasi di Sisi Client dengan Next.js

Sekarang mari kita beralih ke sisi client dengan Next.js. Kita akan membuat helper function untuk menangani autentikasi.

Pertama, buat fungsi login yang akan mengirim kredensial ke server:

typescript

export async function login(email: string, password: string): Promise<string> {
  const res = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/login`, {
    method: "POST",
    credentials: "include", // penting untuk menerima cookie
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email, password }),
  });

  if (!res.ok) {
    throw new Error("Login failed");
  }

  const data = await res.json();
  return data.access_token;
}

Perhatikan parameter credentials: "include" yang memastikan browser mengirim dan menerima cookie. Ini penting karena refresh token kita simpan di HttpOnly cookie.

Selanjutnya, kita buat custom hook untuk mengelola state autentikasi:

typescript

import { useState, useEffect, useCallback } from 'react';

export function useAuth() {
  const [accessToken, setAccessToken] = useState<string | null>(null);
  const [user, setUser] = useState<any>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // Cek apakah user sudah login saat component mount
    checkAuthStatus();
  }, []);

  const checkAuthStatus = useCallback(async () => {
    try {
      const token = await getAccessToken();
      if (token) {
        setAccessToken(token);
        // Fetch user data jika diperlukan
        const userData = await fetchUserData(token);
        setUser(userData);
      }
    } catch (error) {
      console.error('Auth check failed:', error);
    } finally {
      setLoading(false);
    }
  }, []);

  const login = useCallback(async (email: string, password: string) => {
    const token = await login(email, password);
    setAccessToken(token);
    await checkAuthStatus();
  }, [checkAuthStatus]);

  const logout = useCallback(async () => {
    await logout();
    setAccessToken(null);
    setUser(null);
  }, []);

  return { accessToken, user, loading, login, logout };
}

Salah tantangan terbesar dalam implementasi JWT di client adalah menangani refresh token secara otomatis ketika access token kadaluarsa. Mari buat wrapper untuk fetch yang menangani ini:

typescript

let accessToken: string | null = null;
let refreshPromise: Promise<string> | null = null;

export async function fetchWithAuth(url: string, options: RequestInit = {}): Promise<Response> {
  // Jika tidak ada access token, coba refresh dulu
  if (!accessToken) {
    accessToken = await refreshAccessToken();
  }

  const response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${accessToken}`,
    },
  });

  // Jika token expired, refresh dan coba lagi
  if (response.status === 401) {
    accessToken = await refreshAccessToken();
    
    // Retry request dengan token baru
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${accessToken}`,
      },
    });
  }

  return response;
}

async function refreshAccessToken(): Promise<string> {
  // Hindari multiple simultaneous refresh
  if (refreshPromise) {
    return refreshPromise;
  }

  refreshPromise = new Promise(async (resolve, reject) => {
    try {
      const res = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/refresh`, {
        method: 'POST',
        credentials: 'include',
      });

      if (!res.ok) {
        throw new Error('Refresh failed');
      }

      const data = await res.json();
      accessToken = data.access_token;
      resolve(data.access_token);
    } catch (error) {
      // Redirect ke login page jika refresh gagal
      window.location.href = '/login';
      reject(error);
    } finally {
      refreshPromise = null;
    }
  });

  return refreshPromise;
}

Fungsi fetchWithAuth ini akan secara otomatis mendeteksi ketika access token kadaluarsa (dengan status 401) dan mencoba untuk mendapatkan token baru sebelum mengulang request. Pola ini memastikan pengalaman user yang mulus tanpa interupsi login berulang.

Auto Renew Token: Menjaga User Tetap Login Selama Aktif

Untuk aplikasi dengan tingkat keamanan tinggi, kita dapat mengimplementasikan auto renew token yang secara proaktif memperbarui token sebelum kadaluarsa.

typescript

export function useTokenAutoRenew() {
  useEffect(() => {
    const renewInterval = setInterval(async () => {
      // Hanya renew jika user aktif
      if (document.visibilityState === 'visible') {
        try {
          await refreshAccessToken();
          console.log('Token renewed successfully');
        } catch (error) {
          console.error('Token renewal failed:', error);
        }
      }
    }, 45 * 60 * 1000); // Coba renew setiap 45 menit

    return () => clearInterval(renewInterval);
  }, []);
}

Hook ini dapat digunakan di component layout utama aplikasi. Dengan interval 45 menit (untuk token dengan masa berlaku 60 menit), kita memastikan token selalu diperbarui sebelum kadaluarsa, selama user aktif menggunakan aplikasi.

Best Practice dan Keamanan JWT

Implementasi JWT yang aman membutuhkan perhatian pada detail-detail penting. Berikut adalah checklist keamanan yang harus diperhatikan:

Pertama, selalu gunakan HTTPS dalam production. JWT traveling melalui jaringan tanpa enkripsi rentan terhadap man-in-the-middle attacks.

Kedua, simpan access token di memory, bukan localStorage atau sessionStorage. Penyimpanan di memory membuat token lebih sulit dicuri melalui XSS attacks.

Ketiga, gunakan HttpOnly Secure cookie untuk refresh token. Ini mencegah akses JavaScript ke refresh token, memberikan lapisan pertahanan tambahan terhadap XSS.

Keempat, implementasikan proper token expiration. Access token sebaiknya memiliki masa berlaku pendek (15-60 menit), sementara refresh token dapat lebih panjang (7-30 hari) dengan mekanisme revocation yang tepat.

Kelima, gunakan algoritma penandatanganan yang kuat. HS256 cukup untuk banyak kasus, tetapi RS256 lebih aman untuk aplikasi dengan skala besar.

Keenam, implementasikan token blacklisting untuk scenarion logout atau ketika token perlu dicabut sebelum masa berlakunya habis.

Kesimpulan

JWT telah merevolusi cara kita berpikir tentang autentikasi di web modern. Dengan pemahaman yang solid tentang konsep dasar dan implementasi yang tepat, developer dapat membangun sistem autentikasi yang aman, skalabel, dan memberikan pengalaman user yang mulus.

Kunci keberhasilan implementasi JWT terletak pada pemahaman bahwa access token dan refresh token memiliki peran dan karakteristik yang berbeda, serta kebutuhan untuk menyimpannya dengan strategi yang sesuai. Access token yang disimpan di memory client dengan masa berlaku pendek, dikombinasikan dengan refresh token yang disimpan aman di HttpOnly cookie, menciptakan keseimbangan yang ideal antara keamanan dan usability.

Dengan panduan lengkap ini, Anda sekarang memiliki fondasi yang kuat untuk mengimplementasikan JWT dalam proyek Laravel dan Next.js Anda. Ingatlah bahwa keamanan adalah proses berkelanjutan, dan selalu penting untuk tetap update dengan perkembangan terbaru dalam praktik keamanan autentikasi.

FAQ Singkat

Apa perbedaan utama JWT dengan session-based authentication?
JWT bersifat stateless di server karena semua informasi ada dalam token itu sendiri, sementara session-based authentication mengharuskan server menyimpan status login. JWT lebih skalabel untuk arsitektur terdistribusi.

Mengapa access token tidak boleh disimpan di localStorage?
localStorage rentan terhadap XSS attacks karena dapat diakses oleh JavaScript. Penyerang dapat mencuri token jika berhasil menyuntikkan kode malicious. Penyimpanan di memory lebih aman.

Apakah JWT aman untuk menyimpan data sensitif?
Tidak, JWT tidak dienkripsi secara default (hanya encoded). Meskipun signature mencegah perubahan data, payload dapat dibaca oleh siapapun yang mendapatkan token. Jangan pernah menyimpan data sensitif seperti password di JWT.

Bagaimana cara mencabut JWT sebelum masa berlakunya habis?
Karena JWT bersifat self-contained, mencabutnya membutuhkan mekanisme tambahan seperti token blacklist atau menggunakan refresh token rotation yang memungkinkan pembatalan refresh token.

Kapan sebaiknya tidak menggunakan JWT?
JWT mungkin tidak ideal ketika Anda perlu mencabut akses secara instan tanpa mekanisme blacklist, atau untuk aplikasi dengan payload sangat besar (karena token akan dikirim di setiap request).