Mengamankan API Anda: Panduan Lengkap Implementasi Laravel Sanctum

Dalam ekosistem pengembangan web modern, API (Application Programming Interface) menjadi tulang punggung bagi berbagai aplikasi, mulai dari Single Page Application (SPA), mobile app, hingga layanan pihak ketiga. Mengamankan API adalah hal krusial untuk melindungi data sensitif dan memastikan akses yang sah. Di sinilah Laravel Sanctum hadir sebagai solusi otentikasi API yang elegan dan ringan.

Artikel ini akan memandu Anda melalui implementasi Laravel Sanctum secara komprehensif, mencakup penggunaan untuk otentikasi SPA berbasis sesi serta otentikasi API token untuk aplikasi mobile atau pihak ketiga. Kami akan membahas setiap langkah, mulai dari instalasi hingga praktik terbaik, memastikan API Anda aman dan siap digunakan.

Apa itu Laravel Sanctum?

Laravel Sanctum adalah paket otentikasi resmi yang disediakan oleh Laravel, dirancang untuk menjadi alternatif yang lebih ringan dan sederhana dibandingkan Laravel Passport untuk sebagian besar kasus penggunaan API. Sanctum menawarkan dua fitur utama untuk otentikasi:

SPA Authentication: Menggunakan otentikasi berbasis sesi/cookie yang mulus untuk Single Page Application (SPA) yang berjalan pada subdomain terpisah dari backend Laravel Anda. Ini memanfaatkan sesi Laravel standar, tanpa perlu token atau mekanisme otentikasi kompleks lainnya di sisi frontend setelah login.
API Token: Menyediakan sistem token API sederhana untuk aplikasi mobile, otentikasi antar-layanan (machine-to-machine), atau akses API pihak ketiga. Token ini dapat diatur kemampuannya (abilities/scopes) dan mudah dikelola (dibuat, dicabut).

Kelebihan utama Sanctum adalah kesederhanaan dan efisiensinya. Ini adalah pilihan ideal jika Anda tidak memerlukan fitur otentikasi OAuth2 lengkap seperti yang ditawarkan oleh Laravel Passport, namun tetap membutuhkan solusi otentikasi API yang kuat dan aman.

Persiapan Awal Implementasi Laravel Sanctum

Sebelum memulai implementasi, pastikan Anda memiliki proyek Laravel yang sudah berjalan. Jika belum, Anda bisa membuatnya dengan perintah:

composer create-project laravel/laravel nama-proyek-anda

1. Instalasi Laravel Sanctum

Langkah pertama adalah menginstal paket Laravel Sanctum melalui Composer:

composer require laravel/sanctum

2. Publikasikan Migrasi dan Konfigurasi

Setelah instalasi, Anda perlu mempublikasikan file migrasi database dan file konfigurasi Sanctum. Ini akan menambahkan tabel personal_access_tokens ke database Anda dan membuat file config/sanctum.php.

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

3. Jalankan Migrasi Database

Setelah file migrasi dipublikasikan, jalankan migrasi database untuk membuat tabel personal_access_tokens yang diperlukan oleh Sanctum:

php artisan migrate

4. Tambahkan Trait ke Model User

Terakhir, tambahkan trait HasApiTokens ke model App\Models\User (atau model pengguna Anda yang lain). Trait ini akan menyediakan metode yang diperlukan untuk mengelola token API.

// app/Models/User.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; // Import trait ini

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

    // ... sisanya model Anda
}

Dengan langkah-langkah ini, persiapan awal Anda untuk menggunakan Laravel Sanctum telah selesai.

Autentikasi SPA (Single Page Application) dengan Sanctum

Sanctum mempermudah otentikasi untuk SPA dengan memanfaatkan sesi Laravel standar. Ini cocok untuk kasus di mana backend Laravel Anda dan frontend SPA Anda berada pada domain atau subdomain yang berbeda (misalnya, api.example.com dan app.example.com).

1. Konfigurasi CORS

Untuk otentikasi SPA, Anda perlu mengonfigurasi Cross-Origin Resource Sharing (CORS) agar browser dapat mengirim cookie dari domain SPA ke domain API Anda.

config/sanctum.php: Tambahkan domain SPA Anda ke array stateful. Ini memberi tahu Sanctum domain mana yang harus menerima otentikasi berbasis sesi.

// config/sanctum.php
'stateful' => [
    'localhost',
    'localhost:3000', // Contoh untuk React/Vue dev server
    '127.0.0.1',
    '127.0.0.1:8000',
    '::1',
    'your-spa-domain.com', // Tambahkan domain SPA Anda di sini
],

.env: Pastikan Anda telah mengonfigurasi domain sesi dengan benar, terutama jika Anda menggunakan subdomain.

SESSION_DOMAIN=null // Gunakan null jika tidak ada subdomain
// Atau jika menggunakan subdomain:
// SESSION_DOMAIN=.your-main-domain.com // Contoh: .example.com untuk app.example.com dan api.example.com

app/Http/Kernel.php: Pastikan middleware \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class berada dalam group middleware api Anda. Umumnya, ini sudah ada secara default.

// app/Http/Kernel.php
protected $middlewareGroups = [
    'api' => [
        \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
        'throttle:api',
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
    ],
];

2. Mendapatkan CSRF Cookie

Sebelum mencoba login, SPA Anda harus melakukan permintaan GET ke endpoint /sanctum/csrf-cookie. Ini akan mengirimkan cookie CSRF (XSRF-TOKEN) ke browser, yang kemudian harus dikirimkan kembali dengan setiap permintaan POST, PUT, atau DELETE.

Contoh dengan JavaScript (Axios):

import axios from 'axios';

axios.defaults.withCredentials = true; // Penting untuk mengirim cookie
axios.defaults.baseURL = 'http://api.your-domain.com'; // Ganti dengan URL API Anda

async function getCsrfCookie() {
    try {
        await axios.get('/sanctum/csrf-cookie');
        console.log('CSRF cookie obtained!');
    } catch (error) {
        console.error('Failed to get CSRF cookie:', error);
    }
}

getCsrfCookie();

3. Proses Login

Setelah mendapatkan CSRF cookie, Anda dapat melakukan permintaan login ke endpoint API Anda.

// app/Http/Controllers/Auth/LoginController.php atau controller custom Anda

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

class LoginController extends Controller
{
    public function login(Request $request)
    {
        $credentials = $request->validate([
            'email' => ['required', 'email'],
            'password' => ['required'],
        ]);

        if (Auth::attempt($credentials)) {
            $request->session()->regenerate();
            return response()->json(['message' => 'Logged in successfully', 'user' => Auth::user()]);
        }

        return response()->json(['message' => 'Invalid credentials'], 401);
    }
}

Rute untuk login:

// routes/api.php
use App\Http\Controllers\Auth\LoginController;

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

Setelah login berhasil, sesi akan dibuat dan cookie otentikasi akan dikirim ke browser. Permintaan selanjutnya dari SPA ke API Anda akan secara otomatis terotentikasi melalui cookie ini.

4. Melindungi Rute SPA

Untuk melindungi rute yang memerlukan otentikasi sesi, gunakan middleware auth:sanctum:

// routes/api.php
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', function (Request $request) {
        return $request->user();
    });

    // Rute API lain yang terproteksi
});

5. Proses Logout

Untuk logout, Anda cukup mencabut sesi pengguna.

// app/Http/Controllers/Auth/LoginController.php atau controller custom Anda

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

class LoginController extends Controller
{
    public function logout(Request $request)
    {
        Auth::guard('web')->logout(); // Pastikan Anda menggunakan guard 'web' atau sesuai konfigurasi sesi Anda
        $request->session()->invalidate();
        $request->session()->regenerateToken();

        return response()->json(['message' => 'Logged out successfully']);
    }
}

Rute untuk logout:

// routes/api.php
Route::post('/logout', [LoginController::class, 'logout'])->middleware('auth:sanctum');

Autentikasi API Token dengan Sanctum

Autentikasi API token cocok untuk aplikasi mobile, otentikasi antar-layanan, atau kasus di mana Anda tidak dapat mengandalkan sesi berbasis cookie (misalnya, ketika tidak ada browser).

1. Membuat Personal Access Token

Setiap pengguna dapat memiliki banyak token API pribadi. Token ini dapat diberi nama dan diberi 'kemampuan' (abilities/scopes) untuk mengontrol akses ke fitur-fitur tertentu.

// app/Http/Controllers/Api/TokenController.php (Contoh)

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use App\Models\User;

class TokenController extends Controller
{
    public function createToken(Request $request)
    {
        $request->validate([
            'email' => 'required|email',
            'password' => 'required',
            'token_name' => 'required',
            'abilities' => 'nullable|array', // Contoh: ['server:update', 'task:create']
        ]);

        $user = User::where('email', $request->email)->first();

        if (! $user || ! Hash::check($request->password, $user->password)) {
            return response()->json(['message' => 'Invalid credentials'], 401);
        }

        $token = $user->createToken($request->token_name, $request->abilities ?? ['*']);

        return response()->json([
            'token' => $token->plainTextToken,
            'message' => 'Token created successfully'
        ]);
    }

    public function revokeToken(Request $request)
    {
        // Mencabut token yang sedang digunakan oleh request saat ini
        $request->user()->currentAccessToken()->delete();

        return response()->json(['message' => 'Current token revoked successfully']);
    }

    public function revokeSpecificToken(Request $request, $tokenId)
    {
        // Mencabut token spesifik berdasarkan ID
        $request->user()->tokens()->where('id', $tokenId)->delete();

        return response()->json(['message' => 'Specific token revoked successfully']);
    }
}

Rute untuk mengelola token:

// routes/api.php
use App\Http\Controllers\Api\TokenController;

Route::post('/tokens/create', [TokenController::class, 'createToken']);

Route::middleware('auth:sanctum')->group(function () {
    Route::delete('/tokens/revoke', [TokenController::class, 'revokeToken']);
    Route::delete('/tokens/revoke/{id}', [TokenController::class, 'revokeSpecificToken']);
});

Saat token dibuat, Anda hanya akan melihat plainTextToken satu kali. Pastikan untuk menyimpannya dengan aman di sisi klien, karena ini tidak dapat diambil kembali dari database.

2. Menggunakan Token untuk Mengakses API

Klien (aplikasi mobile, layanan pihak ketiga) harus mengirimkan token ini di header Authorization dengan skema Bearer:

Authorization: Bearer YOUR_PLAIN_TEXT_TOKEN

Contoh dengan cURL:

curl -H "Authorization: Bearer YOUR_PLAIN_TEXT_TOKEN" http://api.your-domain.com/api/user

3. Melindungi Rute API Token

Sama seperti SPA, untuk melindungi rute yang memerlukan otentikasi token, gunakan middleware auth:sanctum.

// routes/api.php
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/profile', function (Request $request) {
        return $request->user();
    });

    // Memproteksi rute dengan kemampuan/scope tertentu
    Route::get('/server-status', function (Request $request) {
        // Hanya bisa diakses oleh token dengan kemampuan 'server:status' atau '*'
        return response()->json(['status' => 'Server is running']);
    })->middleware('auth:sanctum', 'abilities:server:status');

    // Rute lain yang terproteksi oleh token
});

Jika token tidak valid atau tidak memiliki kemampuan yang diperlukan, permintaan akan ditolak dengan status 401 (Unauthorized) atau 403 (Forbidden).

Praktik Terbaik dan Pertimbangan Keamanan

Selalu Gunakan HTTPS: Otentikasi, baik SPA maupun token, harus selalu dilakukan melalui koneksi HTTPS. Ini melindungi token atau sesi dari intersepsi.
Kelola Token dengan Hati-hati: Jika Anda membuat token API untuk klien, pastikan klien menyimpan token tersebut dengan aman dan tidak mengeksposnya.
Pencabutan Token (Token Revocation): Sediakan mekanisme bagi pengguna untuk mencabut token mereka jika terjadi pelanggaran keamanan atau ketika token tidak lagi diperlukan. Sanctum menyediakan metode $user->tokens()->delete() atau $user->currentAccessToken()->delete() untuk ini.
Batasan Kemampuan (Abilities/Scopes): Gunakan kemampuan token secara bijak. Berikan hanya kemampuan yang benar-benar diperlukan oleh klien atau aplikasi yang menggunakan token tersebut (Prinsip Hak Akses Terkecil).
Rate Limiting: Terapkan batasan laju (rate limiting) pada endpoint API Anda untuk mencegah serangan brute-force atau DDoS. Laravel menyediakan middleware throttle untuk ini.
Audit Logging: Catat aktivitas penting seperti pembuatan token, login yang gagal, dan pencabutan token untuk tujuan audit keamanan.

Kesimpulan

Laravel Sanctum adalah solusi otentikasi API yang kuat, ringan, dan fleksibel untuk ekosistem Laravel. Baik Anda membangun Single Page Application dengan otentikasi berbasis sesi, atau memerlukan otentikasi token sederhana untuk aplikasi mobile dan layanan pihak ketiga, Sanctum menyediakan fondasi yang kokoh dan mudah diimplementasikan.

Dengan mengikuti panduan ini, Anda kini memiliki pemahaman yang mendalam tentang cara mengimplementasikan dan mengamankan API Anda menggunakan Laravel Sanctum. Ingatlah untuk selalu menerapkan praktik terbaik keamanan untuk memastikan data pengguna Anda terlindungi dengan baik.

TAGS: Laravel, Sanctum, API Authentication, Web Development, PHP, Security, REST API, SPA
A visually appealing image featuring a Laravel logo with a digital lock icon overlaid on top, surrounded by abstract code snippets and a network diagram, symbolizing API security and development. The color scheme should be clean and professional, using greens, blues, and grays to convey security and technology.

Lokasi:

Zams Coding