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

Blog / Keamanan / Cara Menerapkan Role dan Permi...
Keamanan

Cara Menerapkan Role dan Permission Menggunakan Spatie Laravel Permission

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
8 min read
13 views

Membangun kontrol akses berbasis peran (RBAC) di Laravel: instalasi, seeder, middleware, Blade directive, policy, sampai pengujian.

Pendahuluan

Begitu aplikasi punya lebih dari satu jenis pengguna (admin, staf gudang, kasir, pelanggan), muncul pertanyaan: siapa boleh melakukan apa? Menulis if ($user->role == 'admin') di mana-mana cepat menjadi berantakan dan rawan terlewat. Padahal akses yang bolong adalah penyebab kebocoran data paling umum (Broken Access Control, peringkat pertama OWASP Top 10).

Paket spatie/laravel-permission menyediakan pendekatan standar: pengguna memiliki role, role memiliki permission, dan aplikasi memeriksa permission, bukan nama role.

Konsep Dasar

User ──has──► Role ──has──► Permission
 │                              ▲
 └──────── (bisa langsung) ─────┘
  • Permission: kemampuan spesifik, misalnya produk.lihat, produk.ubah, pesanan.hapus.
  • Role: kumpulan permission, misalnya admin, staf-gudang, kasir.
  • Pengguna mendapat role (atau permission langsung untuk kasus khusus).

Aturan praktis yang membuat kode tahan perubahan: periksa permission di kode, tetapkan role di data. Dengan begitu, mengubah apa yang boleh dilakukan "kasir" cukup lewat database, tanpa menyentuh kode.

1. Instalasi

composer require spatie/laravel-permission

php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
php artisan optimize:clear
php artisan migrate

Migrasi membuat tabel roles, permissions, model_has_roles, model_has_permissions, dan role_has_permissions.

Tambahkan trait ke model User:

// app/Models/User.php
use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
    // ...
}

2. Mendaftarkan Middleware (Laravel 11+)

Di Laravel 11 ke atas, alias middleware didaftarkan di bootstrap/app.php.

// bootstrap/app.php
use Spatie\Permission\Middleware\PermissionMiddleware;
use Spatie\Permission\Middleware\RoleMiddleware;
use Spatie\Permission\Middleware\RoleOrPermissionMiddleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'role'               => RoleMiddleware::class,
        'permission'         => PermissionMiddleware::class,
        'role_or_permission' => RoleOrPermissionMiddleware::class,
    ]);
})

3. Membuat Role dan Permission dengan Seeder

Simpan definisi akses di seeder agar bisa diulang di semua lingkungan.

php artisan make:seeder RolePermissionSeeder
// database/seeders/RolePermissionSeeder.php
namespace Database\Seeders;

use App\Models\User;
use Illuminate\Database\Seeder;
use Spatie\Permission\Models\{Permission, Role};
use Spatie\Permission\PermissionRegistrar;

class RolePermissionSeeder extends Seeder
{
    public function run(): void
    {
        // bersihkan cache agar perubahan langsung terbaca
        app(PermissionRegistrar::class)->forgetCachedPermissions();

        $permissions = [
            'produk.lihat', 'produk.tambah', 'produk.ubah', 'produk.hapus',
            'pesanan.lihat', 'pesanan.ubah', 'pesanan.hapus',
            'laporan.lihat',
            'pengguna.kelola',
        ];

        foreach ($permissions as $name) {
            Permission::findOrCreate($name, 'web');
        }

        // role => daftar permission
        $roles = [
            'admin'       => $permissions,
            'staf-gudang' => ['produk.lihat', 'produk.ubah', 'pesanan.lihat'],
            'kasir'       => ['produk.lihat', 'pesanan.lihat', 'pesanan.ubah'],
            'viewer'      => ['produk.lihat', 'pesanan.lihat', 'laporan.lihat'],
        ];

        foreach ($roles as $roleName => $perms) {
            Role::findOrCreate($roleName, 'web')->syncPermissions($perms);
        }

        // akun admin awal (ganti password segera setelah login pertama)
        $admin = User::firstOrCreate(
            ['email' => 'admin@contoh-domain.com'],
            ['name' => 'Administrator', 'password' => bcrypt(str()->random(20))]
        );
        $admin->assignRole('admin');
    }
}
php artisan db:seed --class=RolePermissionSeeder

Gunakan findOrCreate dan syncPermissions agar seeder aman dijalankan berulang kali. Jangan menyimpan password admin yang mudah ditebak di seeder. Lebih baik buat dari variabel .env atau paksa ganti password saat login pertama.

4. Memberi dan Mencabut Akses

$user = User::find(1);

// role
$user->assignRole('kasir');
$user->assignRole(['kasir', 'viewer']);
$user->syncRoles(['staf-gudang']);       // ganti seluruh role
$user->removeRole('kasir');

// permission langsung (untuk pengecualian)
$user->givePermissionTo('laporan.lihat');
$user->revokePermissionTo('laporan.lihat');

// pengecekan
$user->hasRole('admin');                         // true / false
$user->hasAnyRole(['admin', 'kasir']);
$user->can('produk.ubah');                       // cek via Gate Laravel
$user->hasPermissionTo('produk.ubah');
$user->getAllPermissions()->pluck('name');       // semua permission (dari role + langsung)
$user->getRoleNames();                           // koleksi nama role

Verifikasi lewat Tinker:

php artisan tinker
> User::find(1)->getRoleNames()
= Illuminate\Support\Collection {#6342 all: ["admin"]}

> User::find(1)->can('pesanan.hapus')
= true

5. Melindungi Route dengan Middleware

// routes/web.php
Route::middleware(['auth'])->prefix('admin')->name('admin.')->group(function () {

    // satu permission
    Route::get('produk', [ProductController::class, 'index'])
        ->middleware('permission:produk.lihat')
        ->name('products.index');

    // salah satu dari beberapa permission
    Route::put('produk/{product}', [ProductController::class, 'update'])
        ->middleware('permission:produk.ubah|produk.tambah')
        ->name('products.update');

    // seluruh grup hanya untuk role tertentu
    Route::middleware('role:admin')->group(function () {
        Route::resource('pengguna', UserController::class);
    });

    // role ATAU permission
    Route::get('laporan', [ReportController::class, 'index'])
        ->middleware('role_or_permission:admin|laporan.lihat');
});

Tanda | berarti "atau". Pengguna tanpa akses akan menerima respons 403. Untuk pengguna yang belum login, auth sudah mengalihkan ke halaman login.

Middleware di constructor controller

use Illuminate\Routing\Controllers\{HasMiddleware, Middleware};

class ProductController extends Controller implements HasMiddleware
{
    public static function middleware(): array
    {
        return [
            new Middleware('permission:produk.lihat',  only: ['index']),
            new Middleware('permission:produk.tambah', only: ['create', 'store']),
            new Middleware('permission:produk.ubah',   only: ['edit', 'update']),
            new Middleware('permission:produk.hapus',  only: ['destroy']),
        ];
    }
}

6. Menyesuaikan Tampilan dengan Blade Directive

@role('admin')
    <a href="{{ route('admin.pengguna.index') }}">Kelola Pengguna</a>
@endrole

@can('produk.tambah')
    <a href="{{ route('admin.products.create') }}" class="btn btn-primary">Tambah Produk</a>
@endcan

@canany(['produk.ubah', 'produk.hapus'])
    <th>Aksi</th>
@endcanany

@hasanyrole('admin|kasir')
    <p>Selamat bekerja!</p>
@endhasanyrole

Menyembunyikan tombol bukan pengamanan. Itu hanya kenyamanan tampilan. Pengamanan sebenarnya tetap harus ada di route, controller, atau policy. Pengguna bisa saja mengakses URL secara langsung.

7. Menggabungkan dengan Policy

Permission menjawab "boleh melakukan jenis aksi ini?". Untuk pertanyaan yang bergantung pada data ("boleh mengubah pesanan ini?"), kombinasikan dengan Policy.

php artisan make:policy OrderPolicy --model=Order
// app/Policies/OrderPolicy.php
public function update(User $user, Order $order): bool
{
    // admin boleh semua; kasir hanya pesanan di cabangnya
    if ($user->hasRole('admin')) {
        return true;
    }

    return $user->can('pesanan.ubah') && $user->branch_id === $order->branch_id;
}
// Controller
public function update(Request $request, Order $order)
{
    $this->authorize('update', $order);
    // ...
}

Pola ini mencegah IDOR: pengguna dengan permission pesanan.ubah tetap tidak bisa mengubah pesanan milik cabang lain.

8. Super Admin lewat Gate::before

Alih-alih memberi semua permission ke admin satu per satu, beri "kunci master" di satu tempat.

// app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::before(function ($user, $ability) {
        return $user->hasRole('super-admin') ? true : null;
    });
}

Mengembalikan null (bukan false) agar pemeriksaan normal tetap berjalan untuk pengguna lain. Batasi role super-admin ke satu atau dua akun, dan jangan bisa diberikan lewat antarmuka biasa.

9. Cache Permission

Paket ini menyimpan daftar permission di cache agar cepat. Konsekuensinya, perubahan lewat query langsung atau seeder kadang tidak langsung terlihat.

php artisan permission:cache-reset

Perubahan lewat method paket (givePermissionTo, assignRole, dan sebagainya) mengosongkan cache otomatis. Setelah deploy yang mengubah data permission, jalankan perintah di atas.

10. Menguji Hak Akses

Tulis test agar celah akses cepat terdeteksi saat ada perubahan.

use App\Models\User;
use Spatie\Permission\Models\Permission;
use Spatie\Permission\Models\Role;

public function test_kasir_tidak_bisa_menghapus_produk(): void
{
    $this->seed(RolePermissionSeeder::class);

    $kasir = User::factory()->create()->assignRole('kasir');
    $product = Product::factory()->create();

    $this->actingAs($kasir)
        ->delete(route('admin.products.destroy', $product))
        ->assertForbidden();

    $this->assertModelExists($product);
}

public function test_admin_bisa_menghapus_produk(): void
{
    $this->seed(RolePermissionSeeder::class);

    $admin = User::factory()->create()->assignRole('admin');
    $product = Product::factory()->create();

    $this->actingAs($admin)
        ->delete(route('admin.products.destroy', $product))
        ->assertSuccessful();

    $this->assertModelMissing($product);
}

Pada test, panggil seeder (atau reset cache permission) agar role dan permission tersedia.

11. Praktik Terbaik

  • Periksa permission, bukan role, di kode. can('produk.ubah') lebih tahan perubahan daripada hasRole('admin').
  • Beri nama konsisten: modul.aksi (misalnya produk.ubah) memudahkan pencarian dan pengelompokan.
  • Prinsip hak minimum: mulai dari akses sempit, tambah bila perlu.
  • Jangan bergantung pada tampilan: selalu lindungi di sisi server.
  • Catat perubahan hak akses (siapa memberi role apa, kapan) sebagai audit log.
  • Hindari permission langsung ke pengguna kecuali pengecualian. Terlalu banyak membuat audit sulit.
  • Eager load relasi roles dan permissions saat menampilkan daftar pengguna untuk menghindari N+1:
$users = User::with('roles:id,name')->paginate(20);

Checklist

  • ☐ Trait HasRoles terpasang di model User.
  • ☐ Alias middleware role, permission, role_or_permission terdaftar.
  • ☐ Permission dan role dibuat lewat seeder yang aman diulang.
  • ☐ Semua route admin dilindungi middleware, bukan hanya disembunyikan di menu.
  • ☐ Aksi pada data spesifik memakai Policy untuk mencegah IDOR.
  • ☐ Password admin awal tidak ditulis mentah di repository.
  • ☐ Cache permission direset setelah deploy yang mengubah data akses.
  • ☐ Ada test untuk skenario ditolak (403) maupun diizinkan.

Penutup

Spatie Laravel Permission memberi fondasi RBAC yang rapi dengan sedikit kode: role dan permission di database, pemeriksaan lewat middleware, Blade, dan Gate. Kunci keberhasilannya ada pada disiplin: definisikan permission yang granular, periksa di sisi server, kombinasikan dengan Policy untuk pembatasan per data, dan lindungi semuanya dengan test.

Bagikan artikel:

Artikel lainnya