Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / REST API, Integrasi & Automation / Laravel Sanctum: Cara Mengaman...
REST API, Integrasi & Automation

Laravel Sanctum: Cara Mengamankan API untuk Aplikasi Web dan Progressive Web App

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
13 min read
14 views

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.

Overview

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:

  • PWA menyimpan token di localStorage, sehingga satu celah XSS cukup untuk mencuri sesi pengguna,
  • token tidak pernah kedaluwarsa dan tidak bisa dicabut dari sisi pengguna,
  • CORS diatur * bersama supports_credentials, sehingga browser menolak atau, lebih buruk, konfigurasi dilonggarkan sembarangan,
  • service worker menyimpan respons API berisi data pribadi di cache perangkat,
  • 419 CSRF token mismatch dan 401 Unauthenticated diselesaikan dengan menonaktifkan perlindungan.

Hasil akhir:

  • autentikasi cookie untuk PWA dengan CSRF dan session yang aman,
  • token API untuk aplikasi mobile dengan masa berlaku, nama perangkat, dan ability,
  • halaman "Perangkat yang login" untuk mencabut token,
  • konfigurasi CORS dan domain yang benar,
  • aturan service worker yang tidak menyimpan data sensitif,
  • test untuk kedua mode.

Prerequisites

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

Step-by-step Tutorial

Langkah 1: Instalasi

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;
}

Langkah 2: Pilih Mode untuk Setiap Klien

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:

  • Cookie session HttpOnly tidak bisa dibaca JavaScript, sehingga XSS tidak bisa mencurinya (berbeda dengan token di localStorage).
  • Session bisa dicabut dari server dan mengikuti masa berlaku session biasa.
  • Proteksi CSRF bawaan Laravel tetap aktif.

Langkah 3: Konfigurasi Domain untuk Mode Cookie

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.

Langkah 4: CORS yang Ketat

// 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.

Langkah 5: Alur Login PWA dengan Cookie

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.

Langkah 6: Token API untuk Aplikasi Mobile

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();

Langkah 7: Periksa Ability di Route

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
    // ...
}

Langkah 8: Halaman "Perangkat yang Login"

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();

Langkah 9: Service Worker yang Aman untuk PWA

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:

  • Respons API tidak pernah masuk cache service worker. Server juga mengirim Cache-Control: no-store untuk respons API (artikel Panduan Membuat REST API Laravel).
  • Bila PWA perlu data offline (misalnya riwayat iuran milik sendiri), simpan secara eksplisit di IndexedDB, dan hapus saat logout.
  • Saat logout, kirim pesan ke service worker dan bersihkan penyimpanan lokal:
await logout();
navigator.serviceWorker.controller?.postMessage('logout');
indexedDB.deleteDatabase('rw-pwa');

Langkah 10: Test Kedua Mode

// 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();
});

Troubleshooting

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

Best Practices

Keamanan

  • PWA di domain yang sama: cookie session HttpOnly, bukan token di localStorage.
  • Token API: masa berlaku, nama perangkat, ability minimum, disimpan di penyimpanan aman platform.
  • CORS dengan origin eksplisit; jangan * untuk API berkredensial.
  • Cabut semua token saat ganti password atau akun dinonaktifkan; beri pengguna halaman perangkat.
  • Rate limit endpoint penerbitan token seperti endpoint login.
  • Service worker tidak pernah menyimpan respons API.

Performa

  • Session dan cache di Redis untuk banyak pengguna PWA.
  • Kolom last_used_at diperbarui di setiap request token; untuk trafik sangat tinggi, pertimbangkan dampaknya pada database.
  • Prune token kedaluwarsa secara terjadwal.

Maintainability

  • Daftar ability token didefinisikan di satu tempat dan dipetakan ke permission.
  • Satu helper api() di klien untuk CSRF, retry 419, dan penanganan 401.
  • Test untuk penerbitan token, ability, kepemilikan token, dan mode stateful.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
Laravel Sanctum 4.x
Redis 7.x
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya