Laravel Sanctum: Cara Mengamankan API untuk Aplikasi Web dan Progressive Web App
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
Dua mode autentikasi Sanctum dan kapan memakai masing-masing: cookie session untuk SPA dan PWA di domain yang sama, serta token API untuk aplikasi mobile dan integrasi. Lengkap dengan konfigurasi domain, CORS, alur login, manajemen perangkat, ability token, service worker yang aman, dan test.
Aplikasi RW akan diakses dari beberapa jenis klien:
| Klien | Contoh | Mode Sanctum yang tepat |
|---|---|---|
| PWA warga di domain yang sama | https://warga.rw.contoh.id memanggil https://rw.contoh.id/api |
Cookie session (SPA authentication) |
| Panel admin Blade | https://rw.contoh.id/admin |
Session web biasa |
| Aplikasi mobile native | Android/iOS | Token API |
| Integrasi pihak ketiga | Aplikasi kasir koperasi | Token API dengan ability terbatas |
Kesalahan yang paling sering terjadi:
localStorage, sehingga satu celah XSS cukup untuk mencuri sesi pengguna,* bersama supports_credentials, sehingga browser menolak atau, lebih buruk, konfigurasi dilonggarkan sembarangan,419 CSRF token mismatch dan 401 Unauthenticated diselesaikan dengan menonaktifkan perlindungan.Hasil akhir:
| Komponen | Versi |
|---|---|
| PHP | 8.3+ (disarankan 8.4) |
| Laravel | 13.x |
| Laravel Sanctum | 4.x |
| Session/Cache | Redis atau database |
| HTTPS | Wajib (cookie Secure, service worker) |
| Testing | Pest 4 |
php artisan install:api
php artisan migrate
Perintah ini memasang Sanctum, membuat routes/api.php, dan tabel personal_access_tokens. Tambahkan trait ke model User:
// app/Models/User.php
use Laravel\Sanctum\HasApiTokens;
class User extends Authenticatable
{
use HasApiTokens, HasFactory, Notifiable;
}
Aturan keputusan sederhana:
Bila klien berjalan di browser dan bisa berbagi domain induk dengan API, gunakan cookie session. Bila tidak (aplikasi native, server lain, domain berbeda total), gunakan token.
Alasan memilih cookie untuk PWA:
HttpOnly tidak bisa dibaca JavaScript, sehingga XSS tidak bisa mencurinya (berbeda dengan token di localStorage).PWA di warga.rw.contoh.id, API di rw.contoh.id. Keduanya berbagi domain induk rw.contoh.id.
# .env
APP_URL=https://rw.contoh.id
FRONTEND_URL=https://warga.rw.contoh.id
SANCTUM_STATEFUL_DOMAINS=warga.rw.contoh.id,rw.contoh.id
SESSION_DOMAIN=.rw.contoh.id
SESSION_SECURE_COOKIE=true
SESSION_SAME_SITE=lax
SESSION_DRIVER=redis
| Variabel | Fungsi |
|---|---|
SANCTUM_STATEFUL_DOMAINS |
Domain asal request yang diperlakukan sebagai SPA (memakai cookie session) |
SESSION_DOMAIN=.rw.contoh.id |
Cookie session berlaku untuk domain induk dan semua subdomainnya |
SESSION_SAME_SITE=lax |
Cukup karena kedua subdomain dianggap "situs yang sama" oleh browser |
Aktifkan middleware stateful untuk route API:
// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
$middleware->statefulApi();
})
statefulApi() membuat request dari domain di SANCTUM_STATEFUL_DOMAINS ke route API memakai session dan CSRF. Request dari domain lain (misalnya aplikasi mobile) tetap stateless dan wajib memakai token.
Bila PWA berada di domain yang sama persis dengan API (misalnya rw.contoh.id/app), SESSION_DOMAIN cukup null dan CORS tidak diperlukan.
// config/cors.php
return [
'paths' => ['api/*', 'sanctum/csrf-cookie', 'login', 'logout'],
'allowed_methods' => ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
'allowed_origins' => [env('FRONTEND_URL')], // BUKAN '*'
'allowed_origins_patterns' => [],
'allowed_headers' => ['Content-Type', 'X-XSRF-TOKEN', 'X-Requested-With', 'Accept', 'Authorization'],
'exposed_headers' => ['X-Request-Id'],
'max_age' => 3600,
'supports_credentials' => true, // izinkan cookie lintas subdomain
];
supports_credentials tidak boleh dipadukan dengan origin *. Browser akan menolak, dan memang demikian seharusnya: mengizinkan semua origin mengirim cookie pengguna sama dengan mematikan perlindungan CSRF.
Gunakan endpoint login berbasis session yang sama dengan aplikasi web (dari starter kit, Fortify, atau artikel Panduan Implementasi Login dan Logout Laravel). Urutannya:
1. GET /sanctum/csrf-cookie → server mengirim cookie XSRF-TOKEN
2. POST /login → kredensial + header X-XSRF-TOKEN → cookie session
3. GET /api/v1/me → cookie session dikirim otomatis
4. POST /logout → session diinvalidasi
Kode klien dengan fetch:
// pwa/src/api.js
const API = 'https://rw.contoh.id';
function xsrfToken() {
const match = document.cookie.match(/(?:^|;\s*)XSRF-TOKEN=([^;]+)/);
return match ? decodeURIComponent(match[1]) : '';
}
export async function api(path, { method = 'GET', body } = {}) {
const res = await fetch(`${API}${path}`, {
method,
credentials: 'include', // kirim & terima cookie lintas subdomain
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
'X-XSRF-TOKEN': xsrfToken(),
},
body: body ? JSON.stringify(body) : undefined,
});
if (res.status === 419) { // token CSRF kedaluwarsa: ambil ulang lalu coba sekali lagi
await fetch(`${API}/sanctum/csrf-cookie`, { credentials: 'include' });
return api(path, { method, body });
}
if (res.status === 401) {
window.dispatchEvent(new CustomEvent('auth:logout'));
}
if (!res.ok) throw { status: res.status, data: await res.json().catch(() => ({})) };
return res.status === 204 ? null : res.json();
}
export async function login(email, password) {
await fetch(`${API}/sanctum/csrf-cookie`, { credentials: 'include' });
await api('/login', { method: 'POST', body: { email, password } });
return api('/api/v1/me');
}
export const logout = () => api('/logout', { method: 'POST' });
Cookie XSRF-TOKEN sengaja tidak HttpOnly agar JavaScript bisa membacanya dan mengirimkannya kembali sebagai header. Ini aman karena token tersebut tidak berguna tanpa cookie session HttpOnly yang tidak bisa dicuri JavaScript.
Endpoint profil pengguna:
// routes/api.php
Route::middleware('auth:sanctum')->get('v1/me', fn (Request $request) => new \App\Http\Resources\V1\MeResource($request->user()));
// app/Http/Resources/V1/MeResource.php
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'nama' => $this->name,
'email' => $this->email,
'peran' => $this->getRoleNames(),
'izin' => $this->getAllPermissions()->pluck('name'), // untuk menampilkan/menyembunyikan menu di PWA
'rt' => $this->rukunTetangga?->nomor,
];
}
Daftar izin di respons hanya untuk menyesuaikan tampilan PWA. Server tetap memeriksa izin pada setiap endpoint.
Aplikasi native tidak memakai cookie browser. Terbitkan token dengan nama perangkat, ability, dan masa berlaku.
// app/Http/Controllers/Api/V1/TokenController.php
namespace App\Http\Controllers\Api\V1;
use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;
class TokenController extends Controller
{
/** Ability token yang tersedia → permission yang harus dimiliki pengguna */
private const ABILITIES = [
'profil:baca' => null, // semua pengguna
'iuran:baca' => null,
'iuran:bayar' => null,
'kas:baca' => 'kas.view',
'warga:baca' => 'warga.view',
];
public function store(Request $request)
{
$data = $request->validate([
'email' => ['required', 'email'],
'password' => ['required', 'string'],
'nama_perangkat' => ['required', 'string', 'max:100'],
]);
$user = User::where('email', strtolower($data['email']))->first();
if (! $user || ! $user->is_active || ! Hash::check($data['password'], $user->password)) {
throw ValidationException::withMessages(['email' => __('auth.failed')]);
}
$abilities = collect(self::ABILITIES)
->filter(fn ($permission) => $permission === null || $user->can($permission))
->keys()
->all();
$token = $user->createToken($data['nama_perangkat'], $abilities, now()->addDays(60));
return response()->json([
'token' => $token->plainTextToken,
'abilities' => $abilities,
'kedaluwarsa'=> $token->accessToken->expires_at->toIso8601String(),
], 201);
}
public function destroy(Request $request)
{
$request->user()->currentAccessToken()->delete(); // logout perangkat ini
return response()->noContent();
}
}
// routes/api.php
Route::post('v1/token', [V1\TokenController::class, 'store'])->middleware('throttle:login');
Route::delete('v1/token', [V1\TokenController::class, 'destroy'])->middleware('auth:sanctum');
Klien menyimpan token di penyimpanan aman platform (Android Keystore / iOS Keychain) dan mengirimnya di setiap request:
GET /api/v1/iuran HTTP/1.1
Host: rw.contoh.id
Accept: application/json
Authorization: Bearer 12|kR9xL0...
Atur juga masa berlaku global sebagai batas atas, dan prefiks token agar mudah dikenali alat pemindai secret:
// config/sanctum.php
'expiration' => 60 * 24 * 60, // menit (60 hari)
'token_prefix' => env('SANCTUM_TOKEN_PREFIX', 'rw_'),
// routes/console.php
Schedule::command('sanctum:prune-expired --hours=24')->daily();
Daftarkan alias middleware:
// bootstrap/app.php
$middleware->alias([
'abilities' => \Laravel\Sanctum\Http\Middleware\CheckAbilities::class,
'ability' => \Laravel\Sanctum\Http\Middleware\CheckForAnyAbility::class,
]);
// routes/api.php
Route::prefix('v1')->middleware(['auth:sanctum', 'active', 'throttle:api'])->group(function () {
Route::get('iuran', [V1\IuranController::class, 'index'])->middleware('abilities:iuran:baca');
Route::post('iuran/{iuran}/pembayaran', [V1\PembayaranController::class, 'store'])->middleware('abilities:iuran:bayar');
Route::get('kas', [V1\KasController::class, 'index'])->middleware('abilities:kas:baca');
});
Untuk request dengan cookie session (PWA), tokenCan() dan middleware abilities selalu menganggap pengguna memiliki semua ability. Itu sebabnya ability melengkapi, bukan menggantikan, pemeriksaan permission dan Policy di controller:
public function index(Request $request)
{
Gate::authorize('kas.view'); // berlaku untuk cookie maupun token
// ...
}
Beri pengguna kendali atas token mereka sendiri:
// app/Http/Controllers/Api/V1/PerangkatController.php
public function index(Request $request)
{
$saatIni = $request->user()->currentAccessToken();
return $request->user()->tokens()
->latest('last_used_at')
->get(['id', 'name', 'abilities', 'last_used_at', 'expires_at', 'created_at'])
->map(fn ($t) => [
'id' => $t->id,
'nama_perangkat' => $t->name,
'terakhir_aktif' => $t->last_used_at?->toIso8601String(),
'kedaluwarsa' => $t->expires_at?->toIso8601String(),
'perangkat_ini' => $saatIni && method_exists($saatIni, 'getKey') && $saatIni->getKey() === $t->id,
]);
}
public function destroy(Request $request, int $id)
{
$request->user()->tokens()->whereKey($id)->firstOrFail()->delete(); // hanya token milik sendiri
return response()->noContent();
}
public function destroyLainnya(Request $request)
{
$saatIni = $request->user()->currentAccessToken();
$request->user()->tokens()
->when($saatIni && method_exists($saatIni, 'getKey'), fn ($q) => $q->whereKeyNot($saatIni->getKey()))
->delete();
return response()->noContent();
}
// routes/api.php
Route::prefix('v1/perangkat')->middleware('auth:sanctum')->group(function () {
Route::get('/', [V1\PerangkatController::class, 'index']);
Route::delete('lainnya', [V1\PerangkatController::class, 'destroyLainnya']);
Route::delete('{id}', [V1\PerangkatController::class, 'destroy'])->whereNumber('id');
});
Selalu cabut semua token saat pengguna mengganti password atau akunnya dinonaktifkan:
$user->tokens()->delete();
Service worker bisa membuat PWA bekerja offline, tetapi cache yang salah menyimpan data pribadi di perangkat, dan bisa menampilkan data pengguna sebelumnya setelah logout.
// pwa/public/sw.js
const ASET = 'aset-v12';
self.addEventListener('install', (event) => {
event.waitUntil(caches.open(ASET).then((c) => c.addAll(['/', '/offline.html', '/manifest.webmanifest'])));
});
self.addEventListener('fetch', (event) => {
const url = new URL(event.request.url);
// 1) API, autentikasi, dan semua request non-GET: selalu ke jaringan, jangan pernah di-cache
if (url.hostname === 'rw.contoh.id' || event.request.method !== 'GET' || url.pathname.startsWith('/sanctum')) {
return; // biarkan browser menangani seperti biasa
}
// 2) Aset statis milik PWA: cache-first
if (url.origin === self.location.origin && /\.(js|css|png|svg|woff2|webp)$/.test(url.pathname)) {
event.respondWith(
caches.match(event.request).then((hit) => hit || fetch(event.request).then((res) => {
const salinan = res.clone();
caches.open(ASET).then((c) => c.put(event.request, salinan));
return res;
}))
);
return;
}
// 3) Navigasi halaman: network-first dengan halaman offline sebagai cadangan
if (event.request.mode === 'navigate') {
event.respondWith(fetch(event.request).catch(() => caches.match('/offline.html')));
}
});
// Hapus cache aplikasi saat logout
self.addEventListener('message', (event) => {
if (event.data === 'logout') {
caches.keys().then((keys) => Promise.all(keys.filter((k) => k !== ASET).map((k) => caches.delete(k))));
}
});
Aturan yang dipegang:
Cache-Control: no-store untuk respons API (artikel Panduan Membuat REST API Laravel).await logout();
navigator.serviceWorker.controller?.postMessage('logout');
indexedDB.deleteDatabase('rw-pwa');
// tests/Feature/Api/SanctumTest.php
use Laravel\Sanctum\Sanctum;
it('menerbitkan token dengan ability sesuai izin pengguna', function () {
$this->seed(\Database\Seeders\RolePermissionSeeder::class);
$warga = User::factory()->create(['password' => 'Rahasia#2026'])->assignRole('warga');
$this->postJson('/api/v1/token', ['email' => $warga->email, 'password' => 'Rahasia#2026', 'nama_perangkat' => 'Android Budi'])
->assertCreated()
->assertJsonPath('abilities', ['profil:baca', 'iuran:baca', 'iuran:bayar']);
});
it('token tanpa ability ditolak', function () {
$user = User::factory()->create();
Sanctum::actingAs($user, ['profil:baca']);
$this->getJson('/api/v1/iuran')->assertForbidden();
});
it('pengguna hanya bisa mencabut token miliknya', function () {
$a = User::factory()->create();
$b = User::factory()->create();
$tokenB = $b->createToken('hp-b')->accessToken;
Sanctum::actingAs($a, ['*']);
$this->deleteJson("/api/v1/perangkat/{$tokenB->id}")->assertNotFound();
expect($tokenB->fresh())->not->toBeNull();
});
it('PWA dari domain stateful memakai session dan CSRF', function () {
$user = User::factory()->create();
$this->withHeader('Origin', 'https://warga.rw.contoh.id')
->withHeader('Referer', 'https://warga.rw.contoh.id/')
->actingAs($user, 'web')
->getJson('/api/v1/me')
->assertOk()
->assertJsonPath('id', $user->id);
});
it('menolak tanpa autentikasi', function () {
$this->getJson('/api/v1/me')->assertUnauthorized();
});
| Error / Gejala | Penyebab | Solusi |
|---|---|---|
419 CSRF token mismatch dari PWA |
/sanctum/csrf-cookie belum dipanggil, header X-XSRF-TOKEN tidak dikirim, atau cookie tidak tersimpan |
Panggil endpoint itu dulu; kirim header; periksa SESSION_DOMAIN |
401 Unauthenticated setelah login berhasil |
Domain PWA tidak ada di SANCTUM_STATEFUL_DOMAINS atau statefulApi() belum aktif |
Tambahkan domain (tanpa skema https://); aktifkan statefulApi() |
| Cookie tidak tersimpan di browser | SESSION_DOMAIN salah, tidak HTTPS dengan Secure, atau credentials: 'include' tidak dipakai |
Samakan domain induk; gunakan HTTPS; set credentials |
| Error CORS "credentials mode is include" | allowed_origins berisi * atau supports_credentials false |
Origin eksplisit + supports_credentials: true |
| Token tidak kedaluwarsa | Tidak ada expires_at maupun expiration |
Set di createToken() dan config/sanctum.php; jadwalkan prune |
tokenCan() selalu true untuk PWA |
Request memakai cookie session (perilaku Sanctum) | Tetap periksa permission/Policy di server |
| Data pengguna lama muncul setelah logout di PWA | Service worker/IndexedDB menyimpan respons | Jangan cache API; bersihkan penyimpanan saat logout |
Call to undefined method currentAccessToken()->delete() di request cookie |
Request cookie tidak memakai token sungguhan | Untuk mode cookie, logout lewat POST /logout session |
Keamanan
HttpOnly, bukan token di localStorage.* untuk API berkredensial.Performa
last_used_at diperbarui di setiap request token; untuk trafik sangat tinggi, pertimbangkan dampaknya pada database.Maintainability
api() di klien untuk CSRF, retry 419, dan penanganan 401.| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| Laravel Sanctum | 4.x |
| Redis | 7.x |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |
Sebelumnya
Panduan Membuat REST API Laravel Menggunakan API Resource dan Form Request
Berikutnya
API Versioning di Laravel: Strategi Menjaga Kompatibilitas Saat Aplikasi Berkembang
Dokumen ini menjelaskan prosedur konfigurasi autentikasi SSH Key antara server Ubuntu dan GitHub untuk memungkinkan server melakukan operasi Git, seperti clone, pull, dan fetch tanpa menggunakan username dan password akun GitHub.
Peta jalan arsitektur dari satu server hingga banyak server: tahapan pertumbuhan dan sinyal kapan naik tahap, prinsip yang sebaiknya diterapkan sejak awal (stateless, asinkron, data ber-tenant), read replica, pengelolaan data yang terus tumbuh, degradasi yang anggun saat layanan bermasalah, feature...
Menyiapkan lingkungan uji yang jujur, mengukur satu endpoint dengan ApacheBench, mensimulasikan perilaku pengguna sungguhan dengan k6 (skenario, threshold, autentikasi token), menelusuri penyebab request lambat dengan Telescope, memantau server selama pengujian, serta menulis laporan hasil dan angga...
Bagaimana Octane membuat Laravel lebih cepat dengan mem-boot aplikasi sekali dan menyimpannya di memori, apa yang sebenarnya dipercepat (dan yang tidak), risiko kebocoran state antar-request yang wajib dipahami, cara memeriksa kode agar aman untuk Octane, pemasangan dengan FrankenPHP di production,...
03 Nov 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
HijrahKreativa
Kami balas secepatnya
Masuk dulu untuk chat dengan tim kami. Riwayat chat Anda tersimpan di akun.
Masuk