Mengenal Laravel Sanctum dan Cara Menggunakannya
Ketika membangun aplikasi menggunakan Laravel, terutama jika backend dan frontend dikembangkan secara terpisah, kita akan mulai berhadapan dengan satu hal penting: autentikasi.
Misalnya, kamu sedang membuat aplikasi menggunakan Laravel 12 sebagai backend dan React.js sebagai frontend. Pengguna bisa login melalui React, kemudian melihat data dashboard, mengelola produk, atau melakukan transaksi melalui API Laravel.
Pertanyaannya, bagaimana Laravel memastikan bahwa request yang dikirim oleh frontend benar-benar berasal dari pengguna yang sudah login?
Di sinilah Laravel Sanctum dapat digunakan.
Laravel Sanctum merupakan package autentikasi yang disediakan oleh Laravel untuk menangani autentikasi aplikasi SPA (Single Page Application), mobile application, serta API yang menggunakan token. Dibandingkan implementasi OAuth2 yang lebih kompleks, Sanctum menawarkan mekanisme autentikasi yang relatif sederhana dan praktis untuk banyak kebutuhan aplikasi.
Pada artikel ini, kita akan mengenal Laravel Sanctum, memahami cara kerjanya, serta mencoba mengimplementasikannya pada Laravel 12 menggunakan contoh API login, pembuatan token, proteksi route, dan logout.
Apa Itu Laravel Sanctum?
Laravel Sanctum adalah package autentikasi Laravel yang membantu mengamankan aplikasi melalui session-based authentication untuk SPA atau personal access token untuk API, mobile app, dan kebutuhan token-based authentication lainnya.
Sanctum memungkinkan setiap pengguna memiliki token akses yang dapat digunakan untuk melakukan request ke endpoint API tertentu. Token tersebut juga dapat diberikan abilities atau batasan akses sesuai kebutuhan aplikasi.
Contohnya, kita memiliki aplikasi inventory yang menyediakan API untuk mengelola produk. Tidak semua endpoint boleh diakses tanpa login. Ketika pengguna berhasil login, backend dapat memberikan token yang nantinya dikirimkan setiap kali pengguna melakukan request ke endpoint yang membutuhkan autentikasi.
Token tersebut berfungsi sebagai bukti bahwa request telah terautentikasi.
Secara sederhana, alur autentikasi menggunakan token dapat digambarkan seperti berikut:
Pengguna mengirim email dan password ke endpoint login.
Laravel memvalidasi kredensial pengguna.
Jika valid, Laravel membuat API token menggunakan Sanctum.
Token dikirimkan kepada frontend.
Frontend menyimpan token dengan mekanisme penyimpanan yang sesuai.
Token digunakan pada request API berikutnya.
Laravel memvalidasi token sebelum memberikan akses ke endpoint yang dilindungi.
Mengapa Menggunakan Laravel Sanctum?
Sebenarnya Laravel sudah memiliki sistem autentikasi bawaan. Namun, ketika kita membuat aplikasi dengan frontend terpisah atau API yang digunakan oleh aplikasi lain, kita membutuhkan mekanisme autentikasi yang sesuai dengan cara komunikasi tersebut.
Beberapa alasan Laravel Sanctum banyak digunakan antara lain:
1. Implementasinya Relatif Sederhana
Sanctum cocok untuk aplikasi yang membutuhkan autentikasi API tanpa harus membangun sistem token sendiri dari awal.
Kita tidak perlu membuat mekanisme token, validasi token, dan penyimpanan token secara manual.
2. Mendukung API Token
Sanctum dapat digunakan untuk membuat personal access token yang dikirim melalui HTTP Authorization header menggunakan format Bearer Token.
Contohnya:
Authorization: Bearer 1|abc123xyzToken tersebut digunakan Laravel untuk mengenali request yang datang dari pengguna yang telah terautentikasi.
3. Mendukung SPA Authentication
Sanctum juga memiliki mekanisme autentikasi SPA menggunakan session cookie. Ini berbeda dengan API token.
Untuk SPA first-party, seperti frontend React atau Vue yang berkomunikasi dengan backend Laravel, Laravel merekomendasikan pendekatan autentikasi berbasis cookie/session yang disediakan Sanctum, bukan menggunakan personal access token sebagai pengganti mekanisme tersebut.
4. Bisa Digunakan untuk Mobile Application
Token Sanctum juga dapat digunakan oleh aplikasi mobile, misalnya aplikasi Android atau iOS.
Ketika pengguna login melalui aplikasi mobile, backend dapat mengeluarkan token untuk perangkat tersebut. Token kemudian digunakan saat aplikasi mengakses endpoint yang membutuhkan autentikasi.
5. Token Dapat Dicabut
Token yang sudah dibuat dapat dihapus atau dicabut ketika tidak lagi dibutuhkan.
Contohnya ketika pengguna logout, kehilangan perangkat, atau administrator ingin mengakhiri akses sebuah perangkat.
Perbedaan Laravel Sanctum dan Laravel Passport
Banyak developer yang masih bingung ketika harus memilih Sanctum atau Passport.
Keduanya digunakan untuk autentikasi API, tetapi kebutuhan dan kompleksitasnya berbeda.
| Laravel Sanctum | Laravel Passport |
|---|---|
| Relatif sederhana | Lebih kompleks |
| Personal access token | OAuth2 |
| SPA authentication | Mendukung OAuth2 flow |
| Cocok untuk API sederhana hingga menengah | Cocok untuk kebutuhan OAuth2 tertentu |
| Token dan session authentication | OAuth2 authorization server |
Jika aplikasi hanya membutuhkan login API, token untuk mobile application, atau autentikasi SPA first-party, Sanctum sering kali menjadi pilihan yang lebih praktis.
Namun, jika aplikasi membutuhkan fitur dan alur OAuth2 secara spesifik, Passport dapat menjadi pilihan yang lebih tepat.
Jadi, jangan memilih package hanya karena salah satunya lebih populer. Pilih berdasarkan kebutuhan sistem yang sedang dibangun.
Cara Install Laravel Sanctum di Laravel 12
Sekarang kita mulai implementasi Laravel Sanctum.
Pada Laravel 12, cara paling praktis untuk menyiapkan API dan Sanctum pada instalasi baru adalah menggunakan Artisan command berikut:
php artisan install:apiPerintah ini akan menyiapkan dukungan API pada aplikasi Laravel, termasuk instalasi Sanctum dan file routing API.
Setelah proses selesai, jalankan migration:
php artisan migrateLaravel akan menyiapkan tabel yang dibutuhkan, termasuk tabel untuk menyimpan personal access token Sanctum.
Pastikan file routes/api.php sudah tersedia setelah proses instalasi.
Untuk memastikan route API sudah dikenali, jalankan:
php artisan route:list --path=apiJika semuanya berjalan dengan baik, kita bisa mulai membuat endpoint autentikasi.
Menambahkan HasApiTokens pada User Model
Agar model User dapat membuat dan mengelola token Sanctum, kita perlu menambahkan trait HasApiTokens.
Buka file:
app/Models/User.phpTambahkan import berikut:
use Laravel\Sanctum\HasApiTokens;Kemudian tambahkan trait pada model User.
Contoh:
<?php
namespace App\Models;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;
class User extends Authenticatable
{
use HasApiTokens, Notifiable;
// Konfigurasi User lainnya
}Jika model User kamu sudah memiliki trait atau konfigurasi lain, cukup tambahkan HasApiTokens tanpa menghapus konfigurasi yang sudah ada.
Trait ini menyediakan berbagai kemampuan untuk mengelola token pengguna, termasuk membuat token baru dan mengakses daftar token yang dimiliki.
Membuat API Login dengan Laravel Sanctum
Setelah Sanctum terpasang, kita akan membuat endpoint login sederhana yang mengembalikan token jika email dan password pengguna valid.
Untuk contoh ini, kita menggunakan endpoint:
POST /api/loginBuka file:
routes/api.phpTambahkan kode berikut:
<?php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;
use App\Models\User;
Route::post('/login', function (Request $request) {
$request->validate([
'email' => 'required|email',
'password' => 'required|string',
'device_name' => 'required|string|max:255'
]);
$user = User::where('email', $request->email)->first();
if (!$user || !Hash::check($request->password, $user->password)) {
throw ValidationException::withMessages([
'email' => ['Email atau password tidak sesuai.']
]);
}
$token = $user->createToken(
$request->device_name
)->plainTextToken;
return response()->json([
'success' => true,
'message' => 'Login berhasil',
'data' => [
'user' => $user,
'token' => $token
]
]);
});Mari kita pahami bagian yang paling penting.
Validasi Login
$request->validate([
'email' => 'required|email',
'password' => 'required|string',
'device_name' => 'required|string|max:255'
]);Laravel memastikan data yang dikirim oleh client sesuai dengan format yang dibutuhkan.
Memeriksa Password
Hash::check($request->password, $user->password)Laravel membandingkan password yang dikirim dengan password hash yang tersimpan di database.
Jangan pernah membandingkan password plaintext secara langsung dengan password database.
Membuat Token
$user->createToken($request->device_name)->plainTextToken;Bagian ini merupakan inti penggunaan Sanctum untuk API token.
Laravel membuat token untuk pengguna. Token tersebut dapat digunakan untuk autentikasi request berikutnya.
Nama perangkat juga dapat membantu ketika pengguna memiliki beberapa token, misalnya:
Postman
Android Phone
iPhone
React Web Application
Token plaintext diberikan ketika token dibuat. Sanctum menyimpan hash token pada database, sehingga token yang sudah dibuat sebaiknya ditampilkan atau dikirimkan ke client dengan aman dan tidak dicatat sembarangan.
Cara Melindungi API Route Menggunakan Sanctum
Setelah endpoint login berhasil membuat token, langkah berikutnya adalah melindungi route yang hanya boleh diakses pengguna terautentikasi.
Contohnya, kita memiliki endpoint untuk menampilkan profil pengguna.
Tambahkan route berikut pada routes/api.php:
Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
return $request->user();
});Middleware auth:sanctum akan memastikan request sudah memiliki autentikasi yang valid.
Jika request tidak memiliki token valid atau session yang sesuai, Laravel akan menolak akses.
Kita juga bisa melindungi beberapa route sekaligus menggunakan group middleware.
Route::middleware('auth:sanctum')->group(function () {
Route::get('/user', function (Request $request) {
return $request->user();
});
Route::get('/dashboard', function () {
return response()->json([
'message' => 'Dashboard API berhasil diakses'
]);
});
Route::post('/logout', function (Request $request) {
// Logout akan dibuat pada bagian berikut
});
});Cara ini lebih praktis ketika aplikasi memiliki banyak endpoint yang membutuhkan autentikasi.
Cara Mengirim Bearer Token pada Request API
Setelah login berhasil, frontend atau client API harus mengirim token pada request berikutnya.
Format header yang digunakan adalah:
Authorization: Bearer TOKEN_ANDAContohnya:
GET /api/user
Authorization: Bearer 1|abc123xyz
Accept: application/jsonLaravel Sanctum akan memeriksa token tersebut.
Jika token valid, request akan diteruskan dan kita bisa mendapatkan data pengguna melalui:
$request->user()Jika token tidak valid, sudah dihapus, atau tidak dikirim, endpoint yang dilindungi akan menolak request.
Cara Logout dan Menghapus Token Sanctum
Logout pada API token-based authentication dapat dilakukan dengan mencabut token yang sedang digunakan.
Contoh endpoint logout:
Route::middleware('auth:sanctum')->post('/logout', function (Request $request) {
$request->user()->currentAccessToken()->delete();
return response()->json([
'success' => true,
'message' => 'Logout berhasil'
]);
});Ketika endpoint tersebut dipanggil, token aktif pengguna akan dihapus dari database.
Token yang sudah dicabut tidak dapat digunakan lagi untuk melakukan autentikasi.
Perlu diingat bahwa contoh ini ditujukan untuk request yang menggunakan personal access token. Jika request berasal dari SPA yang menggunakan session cookie, mekanisme logout-nya mengikuti session authentication Laravel, bukan menghapus personal access token seperti di atas.
Membatasi Token dengan Abilities
Salah satu fitur menarik Laravel Sanctum adalah token dapat diberikan abilities.
Abilities dapat digunakan untuk menentukan kemampuan yang dimiliki sebuah token.
Contohnya, kita ingin membuat token yang hanya dapat membaca data produk.
Saat membuat token:
$token = $user->createToken(
'read-only-token',
['product:read']
)->plainTextToken;Token tersebut dibuat dengan ability:
product:readPada endpoint tertentu, kita dapat memeriksa ability token:
if (!$request->user()->tokenCan('product:read')) {
abort(403, 'Anda tidak memiliki izin');
}Atau menggunakan middleware abilities untuk membatasi endpoint sesuai abilities token.
Contohnya:
Route::middleware([
'auth:sanctum",
"abilities:product:read"
])->get('/products', function () {
return response()->json([
'message' => 'Daftar produk'
]);
});Abilities membantu memberikan batasan pada token, tetapi jangan menganggap abilities sebagai pengganti authorization aplikasi.
Kita tetap perlu memastikan bahwa pengguna yang sedang login memang berhak mengakses data tertentu, misalnya data milik perusahaan atau tenant yang sama.
Menguji Laravel Sanctum Menggunakan Postman
Setelah endpoint dibuat, kita perlu melakukan pengujian agar memastikan autentikasi berjalan dengan baik.
1. Test Login
Buat request baru di Postman.
Method:
POSTURL:
http://127.0.0.1:8000/api/loginBody → raw → JSON:
{
"email": "admin@example.com",
"password": "password",
"device_name": "Postman"
}Pastikan email dan password tersebut sesuai dengan user yang ada di database.
Jika login berhasil, respons akan berisi token.
2. Test Endpoint User
Buat request baru:
GET http://127.0.0.1:8000/api/userPada tab Authorization:
Type: Bearer Token
Token: masukkan token dari hasil login.
Jika berhasil, Laravel akan mengembalikan data user yang sedang terautentikasi.
3. Test Tanpa Token
Coba request endpoint yang sama tanpa Bearer Token.
Jika endpoint sudah dilindungi auth:sanctum, request seharusnya ditolak dengan status 401 Unauthorized.
Pengujian ini penting untuk memastikan API tidak bisa diakses secara bebas.
4. Test Logout
Panggil endpoint:
POST http://127.0.0.1:8000/api/logoutGunakan token yang masih valid.
Jika logout berhasil, token akan dicabut.
Coba gunakan token yang sama untuk memanggil /api/user kembali. Request seharusnya ditolak karena token sudah tidak aktif.
Masalah yang Sering Terjadi Saat Menggunakan Laravel Sanctum
Dalam implementasi Sanctum, beberapa masalah berikut cukup sering ditemui.
Error 401 Unauthorized
Biasanya terjadi karena:
Token tidak dikirim.
Token salah.
Token sudah dicabut.
Route menggunakan middleware autentikasi.
Konfigurasi SPA session authentication belum benar.
Periksa header Authorization, middleware, dan mekanisme autentikasi yang digunakan aplikasi.
Token Tidak Tersimpan
Pastikan migration Sanctum sudah dijalankan.
Periksa tabel:
personal_access_tokensTabel tersebut digunakan untuk menyimpan informasi token yang dibuat oleh Sanctum.
Tidak Bisa Login
Periksa kembali email dan password.
Pastikan password di database disimpan menggunakan hashing Laravel dan diverifikasi menggunakan Hash::check().
API Berjalan, Tetapi SPA Tidak Bisa Login
Jika frontend React, Vue, atau Next.js menggunakan Sanctum untuk autentikasi SPA berbasis cookie, jangan menggunakan tutorial Bearer Token sebagai konfigurasi yang sama.
SPA authentication membutuhkan konfigurasi stateful domain, session cookie, CSRF, CORS, dan middleware stateful API sesuai dokumentasi Laravel.
Kapan Sebaiknya Menggunakan Laravel Sanctum?
Sanctum cocok digunakan ketika aplikasi membutuhkan autentikasi API sederhana dan SPA authentication.
Contohnya:
Backend Laravel dengan frontend React.
Backend Laravel dengan Next.js.
Aplikasi mobile Android atau iOS.
API untuk aplikasi internal perusahaan.
API yang dikonsumsi oleh client atau integrasi tertentu.
Aplikasi yang membutuhkan personal access token.
Namun, jika sistem membutuhkan OAuth2 secara penuh dengan authorization flow yang kompleks, Laravel Passport mungkin lebih sesuai.
Pemilihan package authentication sebaiknya dilakukan berdasarkan kebutuhan aplikasi, bukan hanya mengikuti tren.
Kesimpulan
Laravel Sanctum merupakan solusi autentikasi yang praktis untuk banyak aplikasi Laravel modern. Dengan fitur API token dan SPA authentication, developer dapat mengamankan endpoint tanpa harus membangun mekanisme autentikasi dari awal.
Pada tutorial ini, kita sudah mengenal Laravel Sanctum, memahami perbedaannya dengan Laravel Passport, menginstal Sanctum pada Laravel 12, membuat token login, melindungi route menggunakan auth:sanctum, membatasi token dengan abilities, serta menguji autentikasi menggunakan Postman.
Jika kamu sedang membangun backend Laravel untuk React, Next.js, aplikasi mobile, atau sistem internal perusahaan, memahami cara kerja Sanctum akan menjadi bekal yang sangat berguna.
Jangan hanya berhenti pada tutorial. Cobalah menerapkan Sanctum pada project sendiri, lalu kembangkan dengan role, permission, token abilities, dan authorization policy sesuai kebutuhan aplikasi.
Tags Artikel
Laravel 12, Laravel Sanctum, API Authentication, REST API, PHP, Bearer Token, Postman, Web Development, API Security, Token Authentication, Laravel API, SPA Authentication, Mobile API, Authentication, PHP Framework
Pendekar Koding — Belajar Teknologi, Membangun Solusi.
Bermanfaat?
Jelajahi artikel lainnya di Pendekar Koding.