Laravel Sanctum untuk Authentication API: Panduan Lengkap

Membangun API yang aman dan efisien adalah fondasi penting dalam pengembangan aplikasi modern. Salah satu tantangan terbesarnya adalah mengimplementasikan sistem autentikasi yang robust, terutama saat berhadapan dengan Single Page Applications (SPA), aplikasi mobile, atau API pihak ketiga. Laravel, sebagai framework PHP terkemuka, menyediakan solusi elegan bernama Laravel Sanctum.

Sanctum bukan sekadar alat, melainkan sebuah pendekatan yang telah terbukti mampu menyederhanakan kompleksitas autentikasi API tanpa mengorbankan keamanan atau performa. Sebagai seorang developer yang sering berkutat dengan RESTful API dan integrasi frontend, saya pribadi merasakan bagaimana Sanctum mengubah cara kami mengelola autentikasi, dari yang semula terasa memakan waktu menjadi sebuah proses yang cepat dan relatif mudah untuk diimplementasikan.

Panduan ini akan membawa Anda menyelami Laravel Sanctum secara mendalam. Kita akan membahas apa itu Sanctum, mengapa ia begitu populer, cara kerjanya yang cerdas, hingga langkah demi langkah implementasi praktis yang bisa Anda terapkan di proyek Anda. Siap membangun API yang terautentikasi dengan Laravel Sanctum? Mari kita mulai!

Mengapa Laravel Sanctum Menjadi Pilihan Utama untuk API Authentication?

Bagi developer yang akrab dengan Laravel, autentikasi API seringkali diasosiasikan dengan Laravel Passport, solusi OAuth2 yang sangat powerful. Namun, untuk banyak kasus penggunaan, Passport terasa terlalu “berat” dan kompleks. Di sinilah Laravel Sanctum bersinar. Sanctum dirancang untuk memberikan solusi autentikasi yang ringan, mudah diimplementasikan, namun tetap sangat aman untuk kebutuhan modern.

Berikut adalah beberapa alasan fundamental mengapa Laravel Sanctum menjadi pilihan favorit banyak developer:

Ringan dan Mudah Dibandingkan dengan Laravel Passport

Laravel Passport adalah implementasi OAuth2 yang lengkap, ideal untuk aplikasi yang membutuhkan autentikasi pihak ketiga dengan berbagai jenis grant (authorization code, client credentials, dll.). Namun, jika Anda hanya membangun API untuk aplikasi frontend Anda sendiri (SPA), aplikasi mobile, atau API yang tidak membutuhkan kompleksitas OAuth2, Passport bisa terasa seperti “membunuh lalat dengan godam”.

Sanctum, di sisi lain, fokus pada autentikasi berbasis token sederhana yang sangat cocok untuk skenario tersebut. Proses instalasi dan konfigurasinya jauh lebih ringkas, memungkinkan Anda untuk cepat fokus pada pengembangan fitur inti aplikasi Anda.

Dua Fungsi Inti: API Token dan SPA Authentication

Kekuatan Sanctum terletak pada kemampuannya menangani dua skenario autentikasi utama:

• API Token Authentication (Bearer Token): Ini adalah metode klasik di mana klien (aplikasi mobile, pihak ketiga) mengirimkan token API yang dihasilkan server di setiap request. Token ini diperiksa untuk memvalidasi identitas dan otorisasi.
• SPA Authentication (Cookie-Based): Untuk Single Page Applications yang berada di subdomain yang sama atau domain terpisah, Sanctum memanfaatkan sistem sesi dan cookie Laravel yang ada. Ini menghilangkan kebutuhan untuk secara manual mengelola token API di frontend, menciptakan pengalaman yang mirip dengan aplikasi web tradisional yang berbasis sesi, namun dengan perlindungan CSRF bawaan.

Pengelolaan Token yang Fleksibel dengan Scopes

Sanctum memungkinkan Anda untuk membuat token API dengan “scopes” atau kemampuan tertentu. Ini berarti Anda bisa memberikan izin yang sangat granular untuk setiap token. Misalnya, satu token bisa hanya memiliki akses untuk “membaca” data, sementara token lain bisa memiliki akses “membaca” dan “menulis”. Fitur ini krusial untuk keamanan dan mengelola akses ke berbagai bagian API Anda.

Selain itu, token API yang dibuat oleh Sanctum dapat dengan mudah di-revoke (dicabut) kapan saja. Ini sangat berguna jika token bocor, atau ketika pengguna melakukan logout dari salah satu perangkat mereka, Anda bisa mencabut token yang terkait dengan sesi tersebut.

Keamanan Bawaan, Termasuk Perlindungan CSRF untuk SPA

Keamanan adalah prioritas utama. Untuk SPA, Sanctum secara otomatis menangani perlindungan CSRF (Cross-Site Request Forgery) yang biasanya menjadi tantangan dalam arsitektur API murni. Dengan Sanctum, Anda tidak perlu khawatir tentang implementasi CSRF secara manual, karena Laravel sudah mengintegrasikannya dengan baik.

Ditambah lagi, penggunaan token API berbasis bearer sendiri, jika diimplementasikan dengan benar (misalnya, selalu melalui HTTPS dan disimpan di tempat yang aman di sisi klien), sudah menjadi standar keamanan yang kuat untuk aplikasi mobile dan pihak ketiga.

Cocok untuk SPA, Mobile Apps, dan Third-Party APIs Sederhana

Seperti yang sudah disinggung, Sanctum adalah pilihan ideal untuk:

• Single Page Applications (SPAs): Baik React, Vue, Angular, atau aplikasi JavaScript modern lainnya.
• Aplikasi Mobile (iOS/Android): Dengan menggunakan autentikasi berbasis token API.
• API Pihak Ketiga Sederhana: Jika Anda hanya perlu memberikan akses token sederhana tanpa kerumitan OAuth2.

Memahami Cara Kerja Laravel Sanctum

Untuk bisa memanfaatkan Laravel Sanctum secara optimal, penting bagi kita untuk memahami bagaimana mekanisme kerjanya di balik layar. Sanctum beroperasi dengan dua pendekatan utama tergantung pada jenis klien yang melakukan autentikasi: SPA (Single Page Application) dan API Token (untuk aplikasi mobile, pihak ketiga, atau bahkan SPA jika diinginkan).

SPA Authentication (Cookie-Based)

Autentikasi SPA dengan Sanctum memanfaatkan sistem sesi dan cookie Laravel yang sudah ada. Ini adalah metode “stateful” karena server menyimpan informasi sesi. Alur kerjanya mirip dengan aplikasi web tradisional:

1. Pengiriman CSRF Cookie: Aplikasi frontend (SPA) pertama-tama membuat permintaan ke endpoint /sanctum/csrf-cookie. Endpoint ini akan mengirimkan cookie XSRF-TOKEN ke browser frontend.
2. Permintaan Login: Frontend kemudian mengirimkan kredensial login (email, password) ke endpoint login Anda. Bersamaan dengan itu, nilai cookie XSRF-TOKEN yang diterima tadi harus dikirimkan kembali sebagai header X-XSRF-TOKEN.
3. Verifikasi di Server: Laravel memverifikasi kredensial dan header X-XSRF-TOKEN. Jika berhasil, server akan membuat sesi autentikasi dan mengirimkan cookie sesi standar Laravel (misalnya laravel_session) ke browser frontend.
4. Permintaan Selanjutnya: Untuk setiap permintaan selanjutnya ke API, browser secara otomatis akan menyertakan cookie sesi. Middleware Sanctum akan memeriksa cookie ini untuk mengautentikasi pengguna.

Pendekatan ini sangat aman karena memanfaatkan perlindungan CSRF Laravel dan tidak mengharuskan frontend menyimpan token secara manual di localStorage atau tempat lain yang rentan terhadap serangan XSS (Cross-Site Scripting). Kunci utamanya adalah memastikan frontend dan backend berada di domain yang saling percaya dan mengonfigurasi SANCTUM_STATEFUL_DOMAINS dengan benar.

API Token Authentication (Bearer Token)

Pendekatan ini digunakan untuk aplikasi yang tidak berbasis browser, seperti aplikasi mobile, aplikasi desktop, atau layanan pihak ketiga yang berkomunikasi dengan API Anda. Ini adalah metode “stateless” karena server tidak menyimpan informasi sesi di antara permintaan.

1. Pembuatan Token: Setelah pengguna terautentikasi (misalnya, melalui endpoint login dengan email/password), server akan membuat API token menggunakan metode createToken() pada objek pengguna. Token ini disimpan dalam tabel personal_access_tokens di database.
2. Pengiriman Token ke Klien: Token mentah (plain-text token) yang dihasilkan dikirimkan kembali ke klien (misalnya, aplikasi mobile). Klien bertanggung jawab untuk menyimpan token ini dengan aman.
3. Permintaan API: Untuk setiap permintaan API selanjutnya, klien harus menyertakan token ini di header Authorization dengan skema Bearer. Contohnya: Authorization: Bearer YOUR_API_TOKEN_HERE.
4. Verifikasi di Server: Middleware Sanctum mencegat permintaan, mengekstrak token dari header Authorization, dan mencari token tersebut di tabel personal_access_tokens. Jika ditemukan dan valid, pengguna dianggap terautentikasi.

Pendekatan ini memberikan fleksibilitas tinggi karena token dapat memiliki scopes tertentu, memungkinkan kontrol granular terhadap izin. Token juga dapat dicabut kapan saja, memberikan kontrol keamanan yang kuat.

Langkah-Langkah Implementasi Laravel Sanctum: Dari Nol Sampai Siap Digunakan

Sekarang saatnya kita masuk ke bagian yang paling praktis: mengimplementasikan Laravel Sanctum di proyek Laravel Anda. Kita akan memulai dari proyek Laravel kosong dan membangun sistem autentikasi API yang fungsional.

Persiapan Awal Proyek Laravel

Jika Anda sudah memiliki proyek Laravel, Anda bisa melewati langkah ini. Namun, jika Anda memulai dari awal, ikuti langkah berikut:

Pertama, buat proyek Laravel baru:

• Buat proyek baru: composer create-project laravel/laravel nama-proyek-api
• Masuk ke direktori proyek: cd nama-proyek-api

Selanjutnya, konfigurasi database Anda. Buka file .env dan sesuaikan pengaturan database Anda (misalnya, untuk MySQL):

• DB_CONNECTION=mysql
• DB_HOST=127.0.0.1
• DB_PORT=3306
• DB_DATABASE=nama_database_anda
• DB_USERNAME=root
• DB_PASSWORD=

Pastikan Anda telah membuat database dengan nama yang sesuai di server database Anda.

Instalasi Laravel Sanctum

Langkah pertama adalah menginstal paket Laravel Sanctum melalui Composer:

• composer require laravel/sanctum

Setelah instalasi selesai, Anda perlu memublikasikan file migrasi Sanctum. Perintah ini akan menyalin file migrasi yang dibutuhkan Sanctum ke direktori database/migrations Anda:

• php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

Anda akan melihat file migrasi baru yang bernama serupa YYYY_MM_DD_HHMMSS_create_personal_access_tokens_table.php. File ini akan membuat tabel personal_access_tokens yang digunakan Sanctum untuk menyimpan API token.

Terakhir, jalankan migrasi database:

• php artisan migrate

Perintah ini akan membuat tabel personal_access_tokens dan tabel default Laravel lainnya jika belum ada.

Konfigurasi Model Pengguna (User Model)

Agar model User Anda dapat menggunakan fitur-fitur Sanctum, Anda perlu menambahkan trait HasApiTokens ke dalamnya. Buka file app/Models/User.php:

• Pastikan ada use Laravel\Sanctum\HasApiTokens; di bagian atas.
• Tambahkan HasApiTokens ke daftar trait yang digunakan oleh kelas User.

Contoh potongan kode di app/Models/User.php akan terlihat seperti ini:

<?php

namespace App\Models;

use Illuminate\Contracts\Auth\MustVerifyEmail;

use Illuminate\Database\Eloquent\Factories\HasFactory;

use Illuminate\Foundation\Auth\User as Authenticatable;

use Illuminate\Notifications\Notifiable;

use Laravel\Sanctum\HasApiTokens; // <-- Tambahkan ini

class User extends Authenticatable

{

use HasApiTokens, HasFactory, Notifiable; // <-- Tambahkan HasApiTokens di sini

// ... sisa kode model

}

Melindungi Route API dengan Middleware Sanctum

Untuk melindungi endpoint API Anda, Anda cukup menerapkan middleware auth:sanctum ke route atau grup route di file routes/api.php. Buka file routes/api.php:

• Anda bisa menambahkan sebuah route yang dilindungi. Misalnya, untuk mengambil informasi pengguna yang sedang login:
• use Illuminate\Http\Request;
• Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
• return $request->user();
• });

Setiap kali request masuk ke /api/user, Sanctum akan mencoba mengautentikasi pengguna berdasarkan cookie sesi (untuk SPA) atau header Authorization: Bearer Token (untuk API token).

Mengatur CORS untuk SPA Authentication (jika diperlukan)

Jika frontend SPA Anda berada di domain yang berbeda dengan backend Laravel Anda (misalnya frontend di http://localhost:3000 dan backend di http://localhost:8000), Anda akan mengalami masalah CORS (Cross-Origin Resource Sharing). Laravel menyediakan paket laravel/cors yang sudah terinstal secara default.

Anda perlu mengonfigurasi file config/cors.php. Pastikan supports_credentials diatur ke true dan allowed_origins mencakup domain frontend Anda.

Contoh konfigurasi config/cors.php:

• 'paths' => ['api/*', 'sanctum/csrf-cookie'],
• 'allowed_methods' => ['*'],
• 'allowed_origins' => ['*'], // Ganti dengan domain frontend Anda di produksi, misal: ['http://localhost:3000', 'https://your-frontend.com']
• 'allowed_origins_patterns' => [],
• 'allowed_headers' => ['*'],
• 'exposed_headers' => [],
• 'max_age' => 0,
• 'supports_credentials' => true, // <-- Ini penting untuk SPA authentication

Selain itu, di file .env, pastikan variabel SANCTUM_STATEFUL_DOMAINS diatur untuk menyertakan domain frontend Anda (tanpa http:// atau https://):

• SANCTUM_STATEFUL_DOMAINS=localhost:3000,your-frontend.com

Membangun Endpoint Login dan Token Generation

Kita akan membuat endpoint login sederhana yang akan mengautentikasi pengguna dan, jika berhasil, menghasilkan API token untuk aplikasi mobile atau mengandalkan cookie sesi untuk SPA.

Buat controller autentikasi:

• php artisan make:controller AuthController

Buka app/Http/Controllers/AuthController.php dan tambahkan metode login. Di sini, kita akan menggunakan Auth::attempt() untuk memvalidasi kredensial. Jika valid, kita akan membuat token API.

Contoh app/Http/Controllers/AuthController.php:

<?php

namespace App\Http\Controllers;

use App\Models\User;

use Illuminate\Http\Request;

use Illuminate\Support\Facades\Auth;

use Illuminate\Support\Facades\Hash;

use Illuminate\Validation\ValidationException;

class AuthController extends Controller

{

public function login(Request $request)

{

$request->validate([

'email' => ['required', 'email'],

'password' => ['required'],

]);

if (! Auth::attempt($request->only('email', 'password'))) {

throw ValidationException::withMessages([

'email' => ['Kredensial tidak valid.'],

]);

}

$user = Auth::user();

// Hasilkan token API untuk aplikasi mobile/pihak ketiga

// Untuk SPA, autentikasi berbasis cookie sudah diatur oleh Sanctum dan Laravel

$token = $user->createToken('auth_token')->plainTextToken;

return response()->json([

'message' => 'Login berhasil!',

'user' => $user,

'token' => $token, // Kirim token untuk klien non-SPA (misal: mobile)

]);

}

}

Tambahkan route untuk endpoint login di routes/api.php:

• Route::post('/login', [AuthController::class, 'login']);

Pastikan Anda memiliki setidaknya satu pengguna di database Anda untuk pengujian. Anda bisa membuat pengguna secara manual atau menggunakan seeder.

Autentikasi Aplikasi Frontend (SPA atau Mobile)

Untuk SPA (Cookie-Based)

Jika Anda menggunakan SPA (misalnya dengan Vue, React, Angular), Anda perlu melakukan beberapa hal di frontend Anda:

1. Request CSRF Cookie: Sebelum melakukan request login, atau sebagai bagian dari inisialisasi aplikasi, lakukan request GET ke /sanctum/csrf-cookie. Ini akan membuat Laravel mengirimkan cookie XSRF-TOKEN ke browser Anda.
2. Konfigurasi Axios (atau HTTP Client lainnya): Pastikan client HTTP Anda mengirimkan cookie bersama request. Untuk Axios, ini berarti mengatur withCredentials: true.
3. Login Request: Kirim kredensial login Anda ke endpoint /api/login yang sudah kita buat.

Contoh penggunaan Axios di frontend (JavaScript):

• axios.defaults.withCredentials = true;
• axios.defaults.baseURL = 'http://localhost:8000/api'; // Ganti dengan URL API Anda

async function loginUser() {

try {

// 1. Dapatkan CSRF cookie

await axios.get('/sanctum/csrf-cookie');

// 2. Lakukan request login

const response = await axios.post('/login', {

email: 'user@example.com',

password: 'password'

});

console.log('Login berhasil:', response.data);

// 3. Sekarang Anda bisa mengakses protected routes

const userResponse = await axios.get('/user');

console.log('User data:', userResponse.data);

} catch (error) {

console.error('Login gagal:', error.response.data);

}

}

loginUser();

Untuk Mobile Apps/Third-Party (Token-Based)

Untuk aplikasi mobile atau klien yang tidak berbasis browser, setelah Anda menerima token dari endpoint login, Anda harus menyimpannya dengan aman di sisi klien. Untuk setiap request selanjutnya ke protected endpoint API, Anda harus menyertakan token ini sebagai header Authorization dengan skema Bearer.

Contoh request HTTP dengan token:

• Header: Authorization: Bearer YOUR_GENERATED_TOKEN_HERE
• Endpoint: GET http://localhost:8000/api/user

Pengelolaan API Token Lanjutan

Kekuatan Laravel Sanctum tidak hanya berhenti pada pembuatan token, tetapi juga pada fleksibilitas pengelolaannya, terutama melalui scopes dan kemampuan untuk mencabut token.

Memberi Scopes pada Token

Scopes memungkinkan Anda untuk membatasi kemampuan atau izin yang dimiliki oleh sebuah token. Ini adalah fitur keamanan yang sangat penting. Misalnya, Anda mungkin ingin token tertentu hanya bisa membaca data, sementara token lain bisa membaca dan menulis.

Saat membuat token, Anda bisa memberikan array scopes sebagai argumen kedua:

• $token = $user->createToken('nama_token_anda', ['read', 'create']);

Dalam contoh di atas, token ini hanya akan memiliki kemampuan read dan create. Untuk memeriksa apakah token memiliki kemampuan tertentu, Anda bisa menggunakan metode tokenCan() pada objek pengguna yang terautentikasi:

• if ($request->user()->tokenCan('read')) {
• // Lakukan operasi baca
• }

Anda bisa mendefinisikan scopes yang tersedia di file config/sanctum.php dalam array abilities.

Revoke Token

Mencabut token adalah fitur keamanan krusial, terutama ketika pengguna logout atau jika sebuah token diduga bocor. Anda bisa mencabut token dengan menghapusnya dari database. Sanctum menyediakan cara mudah untuk melakukannya:

Untuk mencabut token yang sedang digunakan oleh pengguna saat ini:

• $request->user()->currentAccessToken()->delete();

Untuk mencabut semua token yang terkait dengan seorang pengguna (misalnya, saat akun mereka dinonaktifkan atau mereka ingin logout dari semua perangkat):

• $user->tokens()->delete();

Dengan mengimplementasikan fitur revoke token, Anda bisa memastikan bahwa akses yang tidak diinginkan dapat segera diputus, meningkatkan keamanan keseluruhan aplikasi Anda.

Pengalaman dan Pertimbangan Praktis dalam Menggunakan Sanctum

Sebagai developer, memahami teori saja tidak cukup. Penting untuk melihat bagaimana Sanctum berintegrasi dengan workflow pengembangan, serta pertimbangan-pertimbangan praktis yang muncul di dunia nyata. Berdasarkan pengalaman saya dan banyak developer lain, ada beberapa poin krusial yang patut diperhatikan.

Kapan Memilih Sanctum vs. Laravel Passport?

Ini adalah pertanyaan klasik. Pilihan antara Sanctum dan Passport sebenarnya tidak rumit jika Anda memahami skenario penggunaannya:

• Gunakan Laravel Sanctum jika:

1. Anda membangun API untuk SPA (Single Page Application) yang menggunakan Laravel sebagai backend.
2. Anda mengembangkan aplikasi mobile (iOS/Android) yang berkomunikasi dengan API Anda.
3. Anda membutuhkan autentikasi API pihak pertama yang sederhana tanpa kebutuhan OAuth2 yang kompleks.
4. Anda ingin solusi yang ringan dan cepat diimplementasikan.

Gunakan Laravel Passport jika:

1. Anda perlu menyediakan autentikasi OAuth2 untuk aplikasi pihak ketiga yang kompleks.
2. Anda membutuhkan dukungan untuk berbagai jenis OAuth grants (Authorization Code, Client Credentials, Password Grant, dll.).
3. Anda memiliki kebutuhan untuk mengelola klien OAuth (misalnya, menampilkan daftar aplikasi yang terhubung).

Dalam banyak proyek modern, Sanctum seringkali menjadi pilihan yang lebih pragmatis. Saya sendiri cenderung memilih Sanctum untuk proyek-proyek yang tidak secara eksplisit memerlukan ekosistem OAuth2 yang lengkap.

Skalabilitas dan Performa

Sanctum menyimpan token API di database. Ini berarti setiap kali ada permintaan API yang diautentikasi dengan token, database akan diakses untuk memverifikasi token tersebut. Untuk aplikasi dengan volume trafik yang sangat tinggi, ini bisa menjadi bottleneck potensial.

Tips praktis: Untuk kasus ekstrem, Anda bisa mempertimbangkan strategi caching untuk token yang sering diakses atau mengoptimalkan indeks pada tabel personal_access_tokens. Namun, untuk sebagian besar aplikasi, performa database Sanctum sudah sangat memadai dan bukan merupakan masalah utama.

Keamanan Token

Penyimpanan token di sisi klien adalah area yang memerlukan perhatian khusus:

• Untuk SPA (Cookie-Based): Karena menggunakan cookie, risiko XSS untuk pencurian token lebih rendah jika cookie diatur sebagai HttpOnly (yang sudah diatur oleh Laravel secara default). Pastikan selalu menggunakan HTTPS.
• Untuk API Token (Aplikasi Mobile/Pihak Ketiga): Jangan pernah menyimpan token di tempat yang tidak aman (misalnya, kode yang di-hardcode atau plain text). Untuk aplikasi mobile, gunakan secure storage yang disediakan oleh sistem operasi (misalnya, Keychain di iOS, EncryptedSharedPreference di Android). Selalu gunakan HTTPS untuk transmisi token.

Penanganan Refresh Token

Salah satu perbedaan utama antara Sanctum dan Passport adalah bahwa Sanctum tidak memiliki mekanisme refresh token bawaan. Ini berarti jika token API Anda memiliki masa berlaku (yang direkomendasikan untuk keamanan), klien harus mendapatkan token baru setelah token lama kedaluwarsa.

Strategi yang bisa diterapkan:

• Re-login: Ketika token kedaluwarsa, paksa pengguna untuk login ulang. Ini adalah cara paling sederhana tetapi bisa mengganggu pengalaman pengguna.
• Short-lived Token dengan Otomatisasi: Berikan token dengan masa berlaku pendek, dan minta klien untuk secara otomatis meminta token baru saat token lama mendekati kedaluwarsa, selama sesi pengguna masih aktif. Ini mirip dengan konsep rolling token.
• Menggunakan Token Panjang dengan Revoke: Berikan token dengan masa berlaku yang sangat panjang, dan andalkan fitur revoke token jika ada dugaan pelanggaran keamanan. Strategi ini perlu dipertimbangkan dengan cermat karena risiko kebocoran token yang lebih lama.

Saya pribadi cenderung memilih kombinasi token pendek dengan mekanisme “re-login pasif” atau “renew otomatis” di belakang layar jika memungkinkan, untuk menjaga keseimbangan antara keamanan dan kenyamanan pengguna.

Masalah yang Sering Terjadi dan Solusinya

Dalam implementasi teknologi baru, masalah adalah bagian tak terpisahkan dari proses pembelajaran. Berikut adalah beberapa masalah umum yang sering saya temui (dan developer lain juga) saat bekerja dengan Laravel Sanctum, beserta solusi praktisnya.

CORS Error pada SPA

Gejala: Permintaan dari frontend SPA ke backend Laravel Anda diblokir oleh browser dengan pesan “CORS policy: No ‘Access-Control-Allow-Origin’ header is present…” atau sejenisnya.

Penyebab: Konfigurasi Cross-Origin Resource Sharing (CORS) di Laravel tidak mengizinkan domain frontend Anda, atau request tidak menyertakan kredensial yang diperlukan.

Solusi:

• Periksa config/cors.php: Pastikan allowed_origins mencakup domain frontend Anda (gunakan '*' untuk pengembangan, tetapi spesifikkan di produksi). Yang paling penting, pastikan 'supports_credentials' => true,.
• Periksa .env: Pastikan SANCTUM_STATEFUL_DOMAINS menyertakan domain frontend Anda (tanpa http:// atau https://, dan dipisahkan koma jika lebih dari satu). Contoh: SANCTUM_STATEFUL_DOMAINS=localhost:3000,yourfrontend.com.
• Konfigurasi Frontend HTTP Client: Pastikan client HTTP Anda (misalnya Axios) diatur untuk mengirimkan kredensial. Contoh untuk Axios: axios.defaults.withCredentials = true;

“Unauthenticated” meskipun Token atau Cookie Dikirim

Gejala: Anda mengirimkan API token atau cookie sesi, tetapi endpoint yang dilindungi dengan auth:sanctum tetap mengembalikan status 401 Unauthorized.

Penyebab: Token salah/kedaluwarsa, middleware tidak diterapkan dengan benar, cookie sesi tidak valid, atau masalah konfigurasi lainnya.

Solusi:

• Debug Token: Untuk API token, pastikan token yang Anda kirimkan sama persis dengan yang dihasilkan server. Periksa apakah token tersebut masih ada di tabel personal_access_tokens dan belum kedaluwarsa.
• Periksa Route dan Middleware: Pastikan route Anda benar-benar menggunakan middleware('auth:sanctum').
• Untuk SPA: Pastikan Anda telah melakukan request ke /sanctum/csrf-cookie sebelum login, dan SANCTUM_STATEFUL_DOMAINS di .env sudah benar. Periksa tab “Application” di devtools browser Anda untuk melihat apakah cookie sesi (laravel_session dan XSRF-TOKEN) sudah terkirim dan disimpan dengan benar.
• Cek Log: Laravel log (storage/logs/laravel.log) mungkin memberikan petunjuk tentang kegagalan autentikasi.

CSRF Token Mismatch untuk SPA

Gejala: Setelah login (atau mencoba request POST/PUT/DELETE), Anda mendapatkan error “CSRF token mismatch”.

Penyebab: Frontend tidak mengirimkan header X-XSRF-TOKEN dengan benar, atau cookie XSRF-TOKEN belum diterima/valid.

Solusi:

• Urutan Request: Pastikan request GET /sanctum/csrf-cookie selalu dilakukan sebelum request login atau request lain yang membutuhkan perlindungan CSRF.
• Axios Configuration: Pastikan axios.defaults.withCredentials = true; diatur. Axios secara otomatis akan menangani pengiriman X-XSRF-TOKEN jika withCredentials diaktifkan dan cookie XSRF-TOKEN sudah ada.
• Domain Match: Pastikan SANCTUM_STATEFUL_DOMAINS di .env sudah benar dan sesuai dengan domain frontend Anda.

Token Tidak Tercatat di Database

Gejala: Anda memanggil $user->createToken(...), tetapi token tidak muncul di tabel personal_access_tokens.

Penyebab: Migrasi belum dijalankan, atau model User tidak menggunakan trait HasApiTokens.

Solusi:

• Jalankan Migrasi: Pastikan Anda sudah menjalankan php artisan migrate setelah memublikasikan migrasi Sanctum. Periksa apakah tabel personal_access_tokens sudah ada di database Anda.
• Tambahkan HasApiTokens Trait: Periksa kembali file app/Models/User.php dan pastikan use HasApiTokens; sudah diimpor dan digunakan oleh model User.

FAQ

Apakah Sanctum aman untuk aplikasi produksi?

Ya, Laravel Sanctum dirancang dengan keamanan sebagai prioritas dan sangat aman untuk aplikasi produksi, asalkan Anda mengikuti praktik keamanan terbaik seperti menggunakan HTTPS, menyimpan token dengan aman di sisi klien, dan mengelola scopes dengan bijak. Untuk SPA, perlindungan CSRF bawaannya juga menambah lapisan keamanan.

Bisakah Sanctum digunakan untuk otentikasi sosial?

Sanctum sendiri tidak secara langsung menyediakan fitur autentikasi sosial (login dengan Google, Facebook, dll.). Namun, Anda bisa mengintegrasikan Laravel Socialite (paket autentikasi sosial Laravel) dengan Sanctum. Setelah pengguna berhasil diautentikasi melalui penyedia sosial, Anda bisa membuat API token untuk mereka menggunakan Sanctum, atau memanfaatkan sesi jika itu adalah SPA.

Bagaimana cara mengatur masa berlaku token?

Secara default, token API yang dibuat oleh Sanctum tidak memiliki masa berlaku. Namun, Anda bisa mengaturnya secara manual saat membuat token dengan menambahkan argumen ketiga ke metode createToken(). Argumen ini adalah objek DateTime yang menentukan kapan token akan kedaluwarsa. Contoh: $token = $user->createToken('auth_token', ['*'], now()->addMinutes(30)); Ini akan membuat token berlaku selama 30 menit.

Apakah Sanctum cocok untuk aplikasi multi-tenant?

Ya, Sanctum dapat bekerja dengan baik dalam aplikasi multi-tenant. Mekanisme autentikasi Sanctum (baik cookie maupun token) adalah agnostik terhadap arsitektur multi-tenant. Anda hanya perlu memastikan bahwa logika aplikasi Anda untuk mengidentifikasi dan mengisolasi data tenant sudah diterapkan dengan benar setelah pengguna terautentikasi melalui Sanctum.

Kesimpulan

Laravel Sanctum adalah solusi autentikasi API yang luar biasa, menawarkan keseimbangan sempurna antara kesederhanaan, fleksibilitas, dan keamanan. Bagi developer yang membangun SPA, aplikasi mobile, atau API pihak pertama, Sanctum adalah pilihan yang jauh lebih ringan dan cepat dibandingkan solusi OAuth2 yang lebih kompleks seperti Laravel Passport.

Melalui panduan ini, kita telah menjelajahi dasar-dasar Sanctum, memahami cara kerjanya yang cerdas, dan yang terpenting, mengimplementasikannya langkah demi langkah. Dari instalasi awal hingga pengelolaan token lanjutan, kini Anda memiliki fondasi yang kuat untuk membangun API yang aman dan terautentikasi.

Dalam praktik pengembangan, saya sangat merekomendasikan Anda untuk selalu mengikuti praktik terbaik keamanan, seperti menggunakan HTTPS, mengelola scopes token dengan cermat, dan mempertimbangkan strategi masa berlaku token. Jangan ragu untuk bereksperimen dan mengadaptasi Sanctum sesuai kebutuhan spesifik proyek Anda. Laravel Sanctum adalah salah satu permata di ekosistem Laravel yang patut Anda kuasai untuk meningkatkan produktivitas dan kualitas API Anda.

TAGS: Laravel, Sanctum, API Authentication, PHP, Web Development, Backend, Developer Tools, Coding, Security

---

Baca Juga

• Panduan Lengkap Belajar Coding untuk Pemula hingga Profesional