Cara Menggunakan Laravel Sanctum untuk Otentikasi: Token-Based Authentication

by

Laravel Sanctum adalah paket otentikasi ringan yang sempurna untuk aplikasi Single Page Applications (SPAs), aplikasi mobile, dan API. Ia menyediakan sistem otentikasi token-based yang sederhana dan mudah digunakan, memungkinkan Anda untuk mengamankan aplikasi Laravel Anda tanpa harus berurusan dengan kerumitan otentikasi berbasis sesi tradisional. Artikel ini akan memandu Anda langkah demi langkah tentang cara menggunakan Laravel Sanctum untuk otentikasi, memastikan Anda memahami konsep dan implementasinya dengan baik.

1. Pengantar Laravel Sanctum dan Otentikasi Token

Sebelum kita menyelam lebih dalam tentang cara menggunakan Laravel Sanctum untuk otentikasi, mari kita pahami dulu apa itu Laravel Sanctum dan mengapa otentikasi token itu penting.

Laravel Sanctum, dulunya dikenal sebagai Laravel Airlock, adalah paket otentikasi yang menyediakan mekanisme otentikasi sederhana untuk SPA, aplikasi mobile, dan API. Sanctum menggunakan “API tokens” atau “personal access tokens” yang disimpan di database. Token ini memungkinkan pengguna untuk mengakses aplikasi Anda tanpa harus mengirimkan kredensial mereka setiap kali mereka membuat permintaan.

Mengapa Otentikasi Token Penting?

  • Keamanan: Token dapat dicabut kapan saja, memberikan kontrol lebih besar atas akses pengguna.
  • Skalabilitas: Otentikasi token stateless, yang berarti server tidak perlu menyimpan informasi sesi. Ini membuat aplikasi lebih mudah diskalakan.
  • Fleksibilitas: Cocok untuk berbagai jenis aplikasi, termasuk SPA, aplikasi mobile, dan API.
  • Kemudahan Penggunaan: Sanctum menyederhanakan proses otentikasi dengan menyediakan API yang mudah digunakan.

Sanctum vs. Otentikasi Sesi Tradisional

Otentikasi sesi tradisional biasanya digunakan untuk aplikasi web berbasis server-side rendering. Otentikasi sesi bergantung pada cookie yang disimpan di browser pengguna. Namun, otentikasi sesi kurang ideal untuk SPA, aplikasi mobile, dan API karena:

  • Masalah CORS (Cross-Origin Resource Sharing): Cookie sesi seringkali bermasalah dengan CORS, terutama ketika aplikasi frontend dan backend dihosting di domain yang berbeda.
  • Kompleksitas: Mengelola sesi di aplikasi modern bisa menjadi rumit.

Sanctum menyelesaikan masalah ini dengan menggunakan token. Token dikirim dalam header permintaan, yang lebih mudah ditangani dengan CORS dan membuat otentikasi lebih sederhana.

2. Instalasi dan Konfigurasi Laravel Sanctum

Langkah pertama dalam cara menggunakan Laravel Sanctum untuk otentikasi adalah menginstal dan mengkonfigurasi paket Sanctum di proyek Laravel Anda.

a. Instalasi via Composer:

Buka terminal Anda dan jalankan perintah berikut di direktori proyek Laravel Anda:

composer require laravel/sanctum

b. Publikasi Konfigurasi dan Migrasi:

Setelah instalasi selesai, publikasikan file konfigurasi dan migrasi Sanctum:

php artisan vendor:publish --provider="LaravelSanctumSanctumServiceProvider"

Perintah ini akan menghasilkan file konfigurasi config/sanctum.php dan file migrasi di direktori database/migrations.

c. Jalankan Migrasi:

Jalankan migrasi untuk membuat tabel yang dibutuhkan oleh Sanctum:

php artisan migrate

Migrasi ini akan membuat tabel personal_access_tokens yang digunakan untuk menyimpan token otentikasi.

d. Setup Model User:

Pastikan model User Anda menggunakan trait HasApiTokens. Buka file app/Models/User.php dan tambahkan trait tersebut:

<?php

namespace AppModels;

use IlluminateContractsAuthMustVerifyEmail;
use IlluminateDatabaseEloquentFactoriesHasFactory;
use IlluminateFoundationAuthUser as Authenticatable;
use IlluminateNotificationsNotifiable;
use LaravelSanctumHasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;

    // ... sisa kode model User ...
}

e. Konfigurasi CORS (Penting untuk SPA):

Jika Anda menggunakan SPA, Anda perlu mengkonfigurasi CORS agar aplikasi frontend Anda dapat mengirimkan permintaan ke backend Laravel Anda. Anda dapat mengkonfigurasi CORS melalui file config/cors.php atau melalui middleware. Cara yang umum adalah dengan menggunakan paket fruitcake/laravel-cors:

composer require fruitcake/laravel-cors

Setelah diinstal, tambahkan middleware HandleCors ke kernel HTTP Anda (app/Http/Kernel.php):

    protected $middleware = [
        // ... middleware lainnya ...
        FruitcakeCorsHandleCors::class,
    ];

Anda juga perlu mengkonfigurasi CORS melalui file config/cors.php sesuai dengan kebutuhan aplikasi Anda. Pastikan domain frontend Anda diizinkan.

f. Konfigurasi Sanctum dalam config/sanctum.php:

Periksa file config/sanctum.php dan sesuaikan konfigurasi sesuai kebutuhan Anda. Beberapa opsi yang penting:

  • stateful: Daftar domain yang dianggap sebagai “stateful” (misalnya, domain frontend Anda). Permintaan dari domain-domain ini akan diperlakukan seolah-olah mereka adalah permintaan dari sesi web, dan cookie akan disertakan. Ini penting untuk SPA yang menggunakan Sanctum.
  • expiration: Masa berlaku token (dalam menit).

3. Membuat API Token untuk Pengguna

Setelah Anda menginstal dan mengkonfigurasi Laravel Sanctum, langkah berikutnya dalam cara menggunakan Laravel Sanctum untuk otentikasi adalah membuat API token untuk pengguna.

a. Membuat Rute untuk Membuat Token:

Buat rute API untuk memungkinkan pengguna membuat token. Tambahkan rute berikut ke file routes/api.php:

use IlluminateHttpRequest;
use IlluminateSupportFacadesRoute;

Route::post('/tokens/create', function (Request $request) {
    $user = $request->user(); // Pastikan middleware 'auth:sanctum' melindungi rute ini

    $token = $user->createToken($request->token_name);

    return ['token' => $token->plainTextToken];
});

Penjelasan Kode:

  • auth:sanctum: Middleware ini memastikan bahwa hanya pengguna yang terotentikasi yang dapat mengakses rute ini.
  • $user->createToken($request->token_name): Metode ini membuat token baru untuk pengguna. Argumen $request->token_name adalah nama token, yang dapat Anda gunakan untuk mengidentifikasi tujuan token.
  • $token->plainTextToken: Ini adalah token yang sebenarnya yang perlu Anda kirimkan ke frontend. Perhatikan: plainTextToken hanya tersedia segera setelah token dibuat. Anda tidak dapat mengambilnya kembali nanti. Simpan token ini dengan aman di frontend.

b. Melindungi Rute dengan auth:sanctum Middleware:

Pastikan rute /tokens/create dilindungi oleh middleware auth:sanctum. Ini memastikan bahwa hanya pengguna yang sudah terotentikasi (misalnya, melalui login tradisional) yang dapat membuat token baru. Anda bisa menambahkannya secara manual ke rute:

Route::post('/tokens/create', function (Request $request) {
    // ... kode di atas ...
})->middleware('auth:sanctum');

Atau Anda bisa menambahkannya ke group route:

Route::middleware('auth:sanctum')->group(function () {
    Route::post('/tokens/create', function (Request $request) {
        // ... kode di atas ...
    });

    // Rute API lainnya yang membutuhkan otentikasi
});

c. Membuat Form Login (Jika Belum Ada):

Jika pengguna belum memiliki cara untuk login, Anda perlu membuat form login. Ini di luar cakupan Sanctum, tetapi Laravel menyediakan fitur otentikasi bawaan yang mudah digunakan. Anda bisa menggunakan php artisan make:auth untuk membuat scaffolding otentikasi dasar.

d. Implementasi di Frontend (Contoh dengan JavaScript):

Setelah pengguna login, mereka dapat membuat token. Berikut adalah contoh bagaimana Anda dapat melakukan ini dari frontend menggunakan JavaScript (menggunakan fetch):

fetch('/api/tokens/create', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${localStorage.getItem('authToken')}` // Jika pengguna sudah memiliki token otentikasi
    },
    body: JSON.stringify({
        token_name: 'example-token' // Ganti dengan nama token yang deskriptif
    })
})
.then(response => response.json())
.then(data => {
    console.log('Token: ', data.token);
    // Simpan token di localStorage atau tempat aman lainnya
    localStorage.setItem('api_token', data.token);
})
.catch(error => {
    console.error('Error:', error);
});

Penting: Pastikan pengguna sudah terotentikasi sebelum mencoba membuat token. Contoh di atas mengasumsikan bahwa pengguna sudah memiliki token otentikasi yang disimpan di localStorage. Ini bisa jadi token sesi (misalnya, setelah login melalui form login tradisional) atau token Sanctum yang sudah ada.

4. Mengamankan Rute API dengan Token

Setelah Anda membuat token, Anda dapat menggunakan token tersebut untuk mengakses rute API yang dilindungi.

a. Mengirimkan Token di Header Authorization:

Saat Anda membuat permintaan ke rute API yang dilindungi, Anda perlu menyertakan token di header Authorization. Gunakan skema Bearer untuk menunjukkan bahwa Anda menggunakan token otentikasi Bearer.

Contoh (lanjutan dari contoh JavaScript di atas):

fetch('/api/resource', {  // Ganti /api/resource dengan rute yang ingin Anda akses
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${localStorage.getItem('api_token')}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    }
})
.then(response => response.json())
.then(data => {
    console.log('Data: ', data);
})
.catch(error => {
    console.error('Error:', error);
});

b. Middleware auth:sanctum:

Seperti yang telah disebutkan sebelumnya, middleware auth:sanctum digunakan untuk melindungi rute API. Jika permintaan tidak memiliki token yang valid di header Authorization, middleware akan menolak akses.

Contoh di routes/api.php:

Route::middleware('auth:sanctum')->group(function () {
    Route::get('/resource', function (Request $request) {
        return response()->json([
            'message' => 'Anda berhasil mengakses resource yang dilindungi!',
            'user' => $request->user() // Mendapatkan informasi pengguna yang terotentikasi
        ]);
    });

    // Rute API lainnya yang membutuhkan otentikasi
});

5. Mencabut Token (Token Revocation)

Salah satu keuntungan utama otentikasi token adalah Anda dapat mencabut token kapan saja. Ini sangat penting jika token disusupi atau jika pengguna ingin mencabut akses aplikasi.

a. Membuat Rute untuk Mencabut Token:

Buat rute API untuk mencabut token. Tambahkan rute berikut ke file routes/api.php:

use IlluminateHttpRequest;
use IlluminateSupportFacadesRoute;

Route::post('/tokens/revoke', function (Request $request) {
    $request->user()->currentAccessToken()->delete();

    return response()->json(['message' => 'Token berhasil dicabut.']);
});

Penjelasan Kode:

  • $request->user(): Mendapatkan instance pengguna yang terotentikasi.
  • currentAccessToken(): Mendapatkan token yang sedang digunakan untuk membuat permintaan.
  • delete(): Menghapus token dari database.

b. Melindungi Rute dengan auth:sanctum Middleware:

Sama seperti rute pembuatan token, rute pencabutan token juga harus dilindungi oleh middleware auth:sanctum:

Route::post('/tokens/revoke', function (Request $request) {
    // ... kode di atas ...
})->middleware('auth:sanctum');

c. Implementasi di Frontend (Contoh dengan JavaScript):

fetch('/api/tokens/revoke', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${localStorage.getItem('api_token')}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    }
})
.then(response => response.json())
.then(data => {
    console.log('Pesan: ', data.message);
    // Hapus token dari localStorage
    localStorage.removeItem('api_token');
})
.catch(error => {
    console.error('Error:', error);
});

Setelah token dicabut, permintaan berikutnya yang menggunakan token tersebut akan ditolak oleh middleware auth:sanctum.

6. Menggunakan Multiple API Token

Laravel Sanctum memungkinkan Anda untuk membuat dan mengelola multiple API token per pengguna. Ini berguna jika Anda ingin memberikan akses yang berbeda kepada aplikasi yang berbeda, atau jika Anda ingin membatasi akses ke sumber daya tertentu.

Ketika memanggil $user->createToken($request->token_name), Anda bisa menambahkan kemampuan (abilities) ke token tersebut.

Contoh di Backend:

Route::post('/tokens/create', function (Request $request) {
    $user = $request->user();

    $token = $user->createToken($request->token_name, ['resource:read', 'resource:write']);

    return ['token' => $token->plainTextToken];
})->middleware('auth:sanctum');

Dalam contoh di atas, token yang dibuat memiliki kemampuan resource:read dan resource:write.

Memeriksa Kemampuan di Middleware:

Anda kemudian dapat memeriksa kemampuan token di middleware atau di dalam rute:

Route::get('/resource', function (Request $request) {
    if ($request->user()->tokenCan('resource:read')) {
        return response()->json(['message' => 'Anda memiliki izin untuk membaca sumber daya.']);
    }

    abort(403, 'Anda tidak memiliki izin untuk mengakses sumber daya ini.');
})->middleware('auth:sanctum');

Middleware juga bisa digunakan:

<?php

namespace AppHttpMiddleware;

use Closure;
use IlluminateHttpRequest;

class CheckAbilities
{
    /**
     * Handle an incoming request.
     *
     * @param  IlluminateHttpRequest  $request
     * @param  Closure(IlluminateHttpRequest): (IlluminateHttpResponse|IlluminateHttpRedirectResponse)  $next
     * @param  string  $abilities
     * @return IlluminateHttpResponse|IlluminateHttpRedirectResponse
     */
    public function handle(Request $request, Closure $next, ...$abilities)
    {
        foreach ($abilities as $ability) {
            if (! $request->user()->tokenCan($ability)) {
                abort(403, 'Anda tidak memiliki izin yang cukup.');
            }
        }

        return $next($request);
    }
}

Daftarkan middleware ini di app/Http/Kernel.php:

    protected $routeMiddleware = [
        'auth' => AppHttpMiddlewareAuthenticate::class,
        'cache.headers' => IlluminateHttpMiddlewareSetCacheHeaders::class,
        'can' => IlluminateAuthMiddlewareAuthorize::class,
        'guest' => AppHttpMiddlewareRedirectIfAuthenticated::class,
        'throttle' => IlluminateRoutingMiddlewareThrottleRequests::class,
        'abilities' => AppHttpMiddlewareCheckAbilities::class, // Tambahkan ini
    ];

Gunakan middleware ini pada rute:

Route::get('/resource', function (Request $request) {
    return response()->json(['message' => 'Anda memiliki izin untuk membaca sumber daya.']);
})->middleware(['auth:sanctum', 'abilities:resource:read']);

7. Keamanan Tambahan dan Praktik Terbaik

Selain konfigurasi dasar, berikut adalah beberapa praktik terbaik dan langkah-langkah keamanan tambahan untuk cara menggunakan Laravel Sanctum untuk otentikasi:

  • Gunakan HTTPS: Pastikan aplikasi Anda menggunakan HTTPS untuk mengenkripsi semua lalu lintas, termasuk token otentikasi.
  • Simpan Token dengan Aman: Frontend harus menyimpan token dengan aman. Hindari menyimpannya di cookie (karena rentan terhadap XSS). Gunakan localStorage atau sessionStorage (dengan pertimbangan risiko XSS), dan pertimbangkan untuk mengenkripsi token sebelum menyimpannya.
  • Token Expiration: Konfigurasikan masa berlaku token yang wajar di file config/sanctum.php. Token yang lebih pendek lebih aman, tetapi mungkin membutuhkan pengguna untuk melakukan otentikasi ulang lebih sering.
  • Rate Limiting: Implementasikan rate limiting untuk mencegah serangan brute-force terhadap rute pembuatan token.
  • Monitor Aktivitas Token: Monitor aktivitas token untuk mendeteksi aktivitas yang mencurigakan.
  • XSS Protection: Lindungi aplikasi Anda dari serangan XSS (Cross-Site Scripting) untuk mencegah pencurian token. Gunakan alat dan teknik untuk membersihkan input pengguna dan menghindari menampilkan data pengguna yang tidak terpercaya.
  • CSRF Protection: Sanctum biasanya menangani CSRF (Cross-Site Request Forgery) secara otomatis untuk permintaan stateful (misalnya, dari SPA). Namun, pastikan aplikasi Anda dikonfigurasi dengan benar untuk melindungi terhadap CSRF.

8. Integrasi dengan Library dan Framework Frontend

Sanctum dapat diintegrasikan dengan mudah dengan berbagai library dan framework frontend populer seperti React, Vue.js, dan Angular. Setiap framework memiliki cara sendiri untuk mengelola otentikasi dan membuat permintaan HTTP dengan header otorisasi.

  • React: Anda dapat menggunakan useEffect hook untuk mengambil token dari localStorage dan menambahkannya ke header permintaan.
  • Vue.js: Anda dapat menggunakan Vuex untuk mengelola state otentikasi dan Interceptors di Axios untuk menambahkan token ke header permintaan.
  • Angular: Anda dapat menggunakan Interceptors di HttpClient untuk menambahkan token ke header permintaan.

9. Troubleshooting Umum

Berikut adalah beberapa masalah umum yang mungkin Anda temui saat menggunakan Laravel Sanctum dan cara mengatasinya:

  • CORS Errors: Pastikan CORS dikonfigurasi dengan benar. Periksa file config/cors.php dan pastikan domain frontend Anda diizinkan.
  • 401 Unauthorized Errors: Pastikan token yang Anda kirimkan valid dan belum dicabut. Periksa juga apakah Anda menyertakan token di header Authorization dengan format yang benar (Bearer <token>).
  • TokenMismatchException: Pastikan aplikasi Anda dikonfigurasi dengan benar untuk melindungi terhadap CSRF.

10. Kesimpulan

Artikel ini telah memberikan panduan komprehensif tentang cara menggunakan Laravel Sanctum untuk otentikasi. Dengan mengikuti langkah-langkah ini, Anda dapat dengan mudah mengamankan aplikasi Laravel Anda dengan otentikasi token-based yang sederhana dan efektif. Ingatlah untuk selalu mengikuti praktik terbaik keamanan untuk melindungi token Anda dan aplikasi Anda dari serangan. Laravel Sanctum menyederhanakan otentikasi di aplikasi modern, memungkinkan Anda fokus pada pembangunan fitur inti. Sekarang, Anda sudah memiliki pengetahuan dasar dan lanjutan mengenai cara menggunakan Laravel Sanctum untuk otentikasi, siap untuk diterapkan pada proyek-proyek Anda.