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

Blog / Keamanan / Role-Based Access Control di L...
Keamanan

Role-Based Access Control di Laravel: Studi Kasus Admin, Bendahara, Pengurus, dan Warga

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
14 min read
10 views

Dari matriks hak akses di atas kertas menjadi kode: role dan permission, pembatasan data per RT, kepemilikan data warga, alur persetujuan kas dengan pemisahan tugas, menu dinamis, dan test yang membuktikan setiap aturan.

Overview

Artikel sebelumnya membahas cara kerja spatie/laravel-permission. Kenyataannya, aturan akses aplikasi sungguhan jarang berhenti di "role X boleh aksi Y". Di aplikasi administrasi RW, aturannya terdengar seperti ini:

  • Bendahara boleh mencatat pengeluaran, tetapi tidak boleh menyetujui pengeluaran yang ia catat sendiri.
  • Pengurus RT hanya boleh mengelola warga di RT-nya.
  • Warga hanya boleh melihat tagihan iuran keluarganya sendiri.
  • Seorang pengurus juga warga, sehingga ia punya lebih dari satu peran.

Aturan seperti ini membutuhkan tiga lapisan yang bekerja bersama:

Lapisan Pertanyaan Alat
Fungsional Apakah peran ini boleh melakukan aksi ini sama sekali? Permission (Spatie)
Data Apakah boleh terhadap data yang ini? Policy
Visibilitas Data mana saja yang boleh dilihat dalam daftar? Query scope

Hasil akhir: modul RW dengan empat peran, matriks akses yang terdokumentasi, Policy untuk aturan data, query scope untuk penyaringan daftar, alur persetujuan kas dengan pemisahan tugas, dan test yang mencakup seluruh matriks.

Prerequisites

Komponen Versi
PHP 8.3+ (disarankan 8.4)
Laravel 13.x
spatie/laravel-permission ^8.0
Database MySQL 8.0+ / PostgreSQL 15+
Testing Pest 4

Diasumsikan Anda sudah mengikuti Cara Menerapkan Role dan Permission Menggunakan Spatie Laravel Permission (paket terpasang, trait HasRoles di model User).

Step-by-step Tutorial

Langkah 1: Tulis Matriks Akses Sebelum Menulis Kode

Duduk bersama pengurus RW dan sepakati matriks ini. Dokumen ini nanti menjadi dasar test.

Aksi Admin Bendahara Pengurus RT Warga
Melihat daftar warga Semua Semua RT sendiri —
Menambah/mengubah warga Semua — RT sendiri —
Melihat data keluarga sendiri ✔ ✔ ✔ ✔
Melihat buku kas ✔ ✔ ✔ (ringkasan) Ringkasan publik
Mencatat pemasukan ✔ ✔ — —
Mencatat pengeluaran ✔ ✔ — —
Menyetujui pengeluaran ✔ — ✔ (bukan catatan sendiri) —
Melihat tagihan iuran Semua Semua RT sendiri Keluarga sendiri
Mengekspor laporan ✔ ✔ — —
Mengelola akun & peran ✔ — — —

Dua aturan tambahan yang tidak muat di tabel:

  1. Pemisahan tugas (separation of duties): pencatat pengeluaran tidak boleh menyetujuinya, apa pun perannya.
  2. Pengeluaran di atas Rp 1.000.000 membutuhkan persetujuan pengurus, tidak cukup admin saja. (Batas ini disimpan sebagai pengaturan, bukan di kode.)

Langkah 2: Struktur Data

// Migration ringkas
Schema::create('rukun_tetangga', function (Blueprint $table) {
    $table->id();
    $table->string('nomor', 5);                     // "001"
    $table->string('nama_ketua')->nullable();
    $table->timestamps();
});

Schema::create('keluarga', function (Blueprint $table) {
    $table->id();
    $table->foreignId('rukun_tetangga_id')->constrained('rukun_tetangga')->restrictOnDelete();
    $table->string('nomor_kk', 16)->unique();
    $table->string('alamat');
    $table->timestamps();
});

Schema::table('users', function (Blueprint $table) {
    $table->foreignId('keluarga_id')->nullable()->constrained('keluarga')->nullOnDelete();
    $table->foreignId('rukun_tetangga_id')->nullable()->constrained('rukun_tetangga')->nullOnDelete(); // RT yang diurus (khusus pengurus)
});

Schema::create('transaksi_kas', function (Blueprint $table) {
    $table->id();
    $table->string('jenis', 10);                    // masuk | keluar
    $table->unsignedBigInteger('jumlah');
    $table->string('keterangan');
    $table->string('status', 15)->default('draft'); // draft | menunggu | disetujui | ditolak
    $table->foreignId('dicatat_oleh')->constrained('users');
    $table->foreignId('disetujui_oleh')->nullable()->constrained('users');
    $table->timestamp('disetujui_pada')->nullable();
    $table->timestamps();

    $table->index(['status', 'created_at']);
});

Schema::create('iuran', function (Blueprint $table) {
    $table->id();
    $table->foreignId('keluarga_id')->constrained('keluarga')->cascadeOnDelete();
    $table->string('periode', 7);                   // "2026-10"
    $table->unsignedBigInteger('jumlah');
    $table->timestamp('dibayar_pada')->nullable();
    $table->timestamps();

    $table->unique(['keluarga_id', 'periode']);
});

Perhatikan users.keluarga_id (setiap warga milik satu keluarga) dan users.rukun_tetangga_id (RT yang diurus, hanya terisi untuk pengurus RT). Keduanya berbeda: seorang pengurus RT 003 bisa tinggal di RT 003 atau RT lain.

Langkah 3: Role dan Permission

// app/Enums/Permission.php
enum Permission: string
{
    case WargaView      = 'warga.view';
    case WargaManage    = 'warga.manage';
    case KasView        = 'kas.view';
    case KasCreate      = 'kas.create';
    case KasApprove     = 'kas.approve';
    case IuranView      = 'iuran.view';
    case IuranRecord    = 'iuran.record';
    case LaporanExport  = 'laporan.export';
    case PenggunaManage = 'pengguna.manage';
}
// app/Enums/Role.php
enum Role: string
{
    case Admin     = 'admin';
    case Bendahara = 'bendahara';
    case Pengurus  = 'pengurus';
    case Warga     = 'warga';

    public function permissions(): array
    {
        return match ($this) {
            self::Admin     => Permission::cases(),
            self::Bendahara => [Permission::WargaView, Permission::KasView, Permission::KasCreate,
                                Permission::IuranView, Permission::IuranRecord, Permission::LaporanExport],
            self::Pengurus  => [Permission::WargaView, Permission::WargaManage, Permission::KasView,
                                Permission::KasApprove, Permission::IuranView],
            self::Warga     => [],
        };
    }
}

Warga tidak punya permission sama sekali. Akses warga ke data keluarganya sendiri ditentukan oleh kepemilikan data di Policy, bukan oleh permission. Ini pola penting: "boleh melihat miliknya sendiri" hampir tidak pernah perlu dijadikan permission.

Seed dengan seeder idempoten dari artikel sebelumnya. Seorang pengurus yang juga warga cukup diberi dua role:

$user->syncRoles([Role::Pengurus->value, Role::Warga->value]);

Langkah 4: Query Scope untuk Visibilitas Daftar

Policy menjawab pertanyaan per data. Untuk daftar, Anda butuh query yang hanya mengambil data yang boleh dilihat. Jangan mengambil semua lalu menyaring di PHP.

// app/Models/Keluarga.php
use Illuminate\Database\Eloquent\Builder;

public function scopeVisibleTo(Builder $query, User $user): void
{
    if ($user->hasRole(Role::Admin->value) || $user->hasRole(Role::Bendahara->value)) {
        return;                                                    // lihat semua
    }

    if ($user->can(Permission::WargaView->value) && $user->rukun_tetangga_id) {
        $query->where('rukun_tetangga_id', $user->rukun_tetangga_id); // pengurus: RT sendiri
        return;
    }

    $query->whereKey($user->keluarga_id ?? 0);                     // warga: keluarga sendiri
}
// app/Models/Iuran.php
public function scopeVisibleTo(Builder $query, User $user): void
{
    $query->whereHas('keluarga', fn ($q) => $q->visibleTo($user));
}

Di sini pemeriksaan role dipakai secara sadar: cakupan data "semua RT" memang ditentukan oleh jabatan. Bila cakupan ini sering berubah, jadikan permission tersendiri, misalnya warga.view-all.

Langkah 5: Policy untuk Aturan Per Data

php artisan make:policy KeluargaPolicy --model=Keluarga
php artisan make:policy TransaksiKasPolicy --model=TransaksiKas
// app/Policies/KeluargaPolicy.php
namespace App\Policies;

use App\Enums\{Permission, Role};
use App\Models\{Keluarga, User};

class KeluargaPolicy
{
    public function viewAny(User $user): bool
    {
        return $user->can(Permission::WargaView->value);
    }

    public function view(User $user, Keluarga $keluarga): bool
    {
        return $user->keluarga_id === $keluarga->id                 // keluarga sendiri
            || $this->dalamCakupan($user, $keluarga);
    }

    public function update(User $user, Keluarga $keluarga): bool
    {
        return $user->can(Permission::WargaManage->value)
            && $this->dalamCakupan($user, $keluarga);
    }

    private function dalamCakupan(User $user, Keluarga $keluarga): bool
    {
        if (! $user->can(Permission::WargaView->value)) {
            return false;
        }

        if ($user->hasAnyRole([Role::Admin->value, Role::Bendahara->value])) {
            return true;
        }

        return $user->rukun_tetangga_id !== null
            && $user->rukun_tetangga_id === $keluarga->rukun_tetangga_id;
    }
}
// app/Policies/TransaksiKasPolicy.php
namespace App\Policies;

use App\Enums\Permission;
use App\Models\{TransaksiKas, User};
use Illuminate\Auth\Access\Response;

class TransaksiKasPolicy
{
    public function create(User $user): bool
    {
        return $user->can(Permission::KasCreate->value);
    }

    public function update(User $user, TransaksiKas $trx): bool
    {
        return $user->can(Permission::KasCreate->value)
            && $trx->dicatat_oleh === $user->id
            && $trx->status === 'draft';                            // yang sudah diajukan tidak bisa diubah
    }

    public function approve(User $user, TransaksiKas $trx): Response
    {
        if (! $user->can(Permission::KasApprove->value)) {
            return Response::deny('Anda tidak memiliki izin menyetujui transaksi.');
        }

        if ($trx->status !== 'menunggu') {
            return Response::deny('Transaksi ini tidak dalam status menunggu persetujuan.');
        }

        if ($trx->dicatat_oleh === $user->id) {
            return Response::deny('Pencatat tidak boleh menyetujui transaksinya sendiri.');
        }

        // Diambil dari pengaturan aplikasi (misalnya SettingsStore pada artikel starter kit) atau config
        $batas = (int) config('rw.batas_persetujuan_pengurus', 1_000_000);

        if ($trx->jumlah > $batas && ! $user->hasRole('pengurus')) {
            return Response::deny('Pengeluaran di atas batas wajib disetujui pengurus.');
        }

        return Response::allow();
    }
}

Mengembalikan Response::deny('alasan') memberi pesan jelas ke pengguna, yang sangat membantu di aplikasi seperti ini: pengurus langsung tahu kenapa tombol setuju ditolak.

Catatan: aturan approve sengaja tidak di-bypass oleh admin. Bila Anda memakai Gate::before untuk super admin, pemisahan tugas ikut terlewati. Untuk aturan seperti ini, tambahkan pengecualian di Gate::before, misalnya fn ($user, $ability) => $ability !== 'approve' && $user->hasRole('super-admin') ? true : null.

Langkah 6: Alur Persetujuan di Controller

// app/Http/Controllers/TransaksiKasController.php
public function index(Request $request)
{
    Gate::authorize(Permission::KasView->value);

    $items = TransaksiKas::query()
        ->with(['pencatat:id,name', 'penyetuju:id,name'])
        ->latest()
        ->paginate(20);

    return view('kas.index', compact('items'));
}

public function ajukan(TransaksiKas $trx)
{
    Gate::authorize('update', $trx);

    $trx->update(['status' => 'menunggu']);

    return back()->with('status', 'Transaksi diajukan untuk persetujuan.');
}

public function setujui(Request $request, TransaksiKas $trx)
{
    Gate::authorize('approve', $trx);

    DB::transaction(function () use ($trx, $request) {
        $trx = TransaksiKas::lockForUpdate()->findOrFail($trx->id);   // cegah persetujuan ganda bersamaan

        Gate::forUser($request->user())->authorize('approve', $trx); // periksa ulang setelah dikunci

        $trx->update([
            'status'          => 'disetujui',
            'disetujui_oleh'  => $request->user()->id,
            'disetujui_pada'  => now(),
        ]);
    });

    return back()->with('status', 'Transaksi disetujui.');
}
// routes/web.php
Route::middleware(['auth', 'auth.session'])->group(function () {
    Route::get('kas', [TransaksiKasController::class, 'index'])->name('kas.index');
    Route::post('kas', [TransaksiKasController::class, 'store'])->can('create', TransaksiKas::class);
    Route::post('kas/{trx}/ajukan', [TransaksiKasController::class, 'ajukan'])->name('kas.ajukan');
    Route::post('kas/{trx}/setujui', [TransaksiKasController::class, 'setujui'])->name('kas.setujui');

    Route::get('keluarga', [KeluargaController::class, 'index'])->can('viewAny', Keluarga::class);
    Route::get('keluarga/{keluarga}', [KeluargaController::class, 'show'])->can('view', 'keluarga');
});

lockForUpdate() di dalam transaksi mencegah dua pengurus menyetujui transaksi yang sama pada saat bersamaan.

Langkah 7: Halaman Warga, Hanya Data Sendiri

// app/Http/Controllers/IuranController.php
public function index(Request $request)
{
    $iuran = Iuran::query()
        ->visibleTo($request->user())
        ->with('keluarga:id,nomor_kk,alamat')
        ->latest('periode')
        ->paginate(24);

    return view('iuran.index', compact('iuran'));
}

Controller yang sama melayani admin, bendahara, pengurus, dan warga. Yang berbeda hanyalah data yang dikembalikan scope. Tidak ada percabangan if ($user->hasRole(...)) di controller.

Jangan pernah membaca keluarga_id dari query string untuk warga, misalnya /iuran?keluarga_id=12. Itu pintu IDOR (Insecure Direct Object Reference): warga cukup mengganti angka untuk melihat data tetangganya.

Langkah 8: Menu Dinamis Berdasarkan Izin

// app/View/Composers/NavigationComposer.php
namespace App\View\Composers;

use Illuminate\View\View;

class NavigationComposer
{
    public function compose(View $view): void
    {
        $user = auth()->user();

        $menu = collect([
            ['label' => 'Dasbor',         'route' => 'dashboard',    'can' => null],
            ['label' => 'Data Warga',     'route' => 'keluarga.index', 'can' => 'warga.view'],
            ['label' => 'Buku Kas',       'route' => 'kas.index',    'can' => 'kas.view'],
            ['label' => 'Iuran',          'route' => 'iuran.index',  'can' => null],
            ['label' => 'Laporan',        'route' => 'laporan.index', 'can' => 'laporan.export'],
            ['label' => 'Pengguna',       'route' => 'pengguna.index', 'can' => 'pengguna.manage'],
        ])->filter(fn ($item) => $item['can'] === null || $user?->can($item['can']));

        $view->with('menu', $menu);
    }
}
// app/Providers/AppServiceProvider.php
View::composer('layouts.app', NavigationComposer::class);

Sekali lagi: menu hanyalah kenyamanan. Setiap route di belakang menu tetap memiliki pemeriksaan sendiri.

Langkah 9: Test Seluruh Matriks

// tests/Feature/Rbac/KeluargaAccessTest.php
use App\Models\{Keluarga, RukunTetangga, User};
use Database\Seeders\RolePermissionSeeder;

beforeEach(function () {
    $this->seed(RolePermissionSeeder::class);
    $this->rt1 = RukunTetangga::factory()->create();
    $this->rt2 = RukunTetangga::factory()->create();
    $this->keluargaRt1 = Keluarga::factory()->for($this->rt1)->create();
    $this->keluargaRt2 = Keluarga::factory()->for($this->rt2)->create();
});

it('pengurus RT hanya melihat keluarga di RT-nya', function () {
    $pengurus = User::factory()->create(['rukun_tetangga_id' => $this->rt1->id])->assignRole('pengurus');

    $this->actingAs($pengurus)->get("/keluarga/{$this->keluargaRt1->id}")->assertOk();
    $this->actingAs($pengurus)->get("/keluarga/{$this->keluargaRt2->id}")->assertForbidden();

    expect(Keluarga::visibleTo($pengurus)->pluck('id')->all())->toBe([$this->keluargaRt1->id]);
});

it('warga hanya melihat keluarganya sendiri', function () {
    $warga = User::factory()->create(['keluarga_id' => $this->keluargaRt1->id])->assignRole('warga');

    $this->actingAs($warga)->get("/keluarga/{$this->keluargaRt1->id}")->assertOk();
    $this->actingAs($warga)->get("/keluarga/{$this->keluargaRt2->id}")->assertForbidden();
    $this->actingAs($warga)->get('/keluarga')->assertForbidden();
});
// tests/Feature/Rbac/PersetujuanKasTest.php
use App\Models\{TransaksiKas, User};

beforeEach(fn () => $this->seed(\Database\Seeders\RolePermissionSeeder::class));

it('pencatat tidak bisa menyetujui transaksinya sendiri', function () {
    $pengurus = User::factory()->create()->assignRole(['pengurus', 'bendahara']);
    $trx = TransaksiKas::factory()->menunggu()->create(['dicatat_oleh' => $pengurus->id, 'jumlah' => 200_000]);

    $this->actingAs($pengurus)->post("/kas/{$trx->id}/setujui")->assertForbidden();
});

it('pengurus lain bisa menyetujui', function () {
    $bendahara = User::factory()->create()->assignRole('bendahara');
    $pengurus  = User::factory()->create()->assignRole('pengurus');
    $trx = TransaksiKas::factory()->menunggu()->create(['dicatat_oleh' => $bendahara->id, 'jumlah' => 2_500_000]);

    $this->actingAs($pengurus)->post("/kas/{$trx->id}/setujui")->assertRedirect();

    expect($trx->fresh())->status->toBe('disetujui')->disetujui_oleh->toBe($pengurus->id);
});

it('admin tidak bisa menyetujui pengeluaran di atas batas', function () {
    $admin = User::factory()->create()->assignRole('admin');
    $trx = TransaksiKas::factory()->menunggu()->create(['jumlah' => 5_000_000]);

    $this->actingAs($admin)->post("/kas/{$trx->id}/setujui")->assertForbidden();
});

Setiap baris matriks di Langkah 1 sebaiknya punya minimal satu test "boleh" dan satu test "tidak boleh".

Troubleshooting

Error / Gejala Penyebab Solusi
Pengurus melihat warga RT lain di daftar Daftar tidak memakai visibleTo() Terapkan scope di setiap query daftar, termasuk ekspor dan pencarian
Warga bisa melihat data tetangga lewat ganti ID di URL Hanya daftar yang disaring, detail tidak diperiksa Tambahkan ->can('view', 'keluarga') atau Gate::authorize('view', ...) di setiap route detail
Pesan 403 generik, pengguna bingung Policy mengembalikan false Kembalikan Response::deny('alasan')
Admin bisa menyetujui transaksi sendiri Gate::before super admin melewati Policy Kecualikan ability sensitif dari Gate::before
Transaksi disetujui dua kali Dua request bersamaan lockForUpdate() dalam transaksi dan periksa ulang status
Pengurus RT tanpa rukun_tetangga_id melihat semua data Scope tidak menangani nilai kosong Pastikan cabang default selalu membatasi (seperti whereKey($user->keluarga_id ?? 0))
Ekspor laporan berisi data di luar cakupan Ekspor memakai query terpisah tanpa scope Pakai scope yang sama untuk tampilan dan ekspor

Best Practices

Keamanan

  • Default menolak: setiap scope dan Policy harus berakhir dengan cabang paling ketat.
  • Periksa akses di daftar (scope) dan di detail (Policy); keduanya wajib.
  • Terapkan pemisahan tugas untuk transaksi keuangan dan jangan biarkan super admin melewatinya.
  • Jangan pernah menerima ID pemilik data dari input untuk pengguna biasa; ambil dari pengguna yang login.
  • Catat persetujuan, penolakan, dan perubahan peran di activity log.

Performa

  • Scope visibleTo() harus tetap berupa kondisi SQL agar bisa dipaginasi dan diindeks; pasang indeks pada rukun_tetangga_id dan keluarga_id.
  • Cache izin pengguna sudah ditangani Spatie; hindari query role berulang di dalam loop tampilan dengan memuatnya sekali ($user->loadMissing('roles')).

Maintainability

  • Matriks akses adalah dokumen hidup: simpan di docs/akses.md dan jadikan dasar test.
  • Permission untuk aksi fungsional, Policy untuk aturan data, scope untuk visibilitas daftar. Jangan mencampur ketiganya.
  • Simpan angka bisnis (batas persetujuan) di pengaturan aplikasi, bukan konstanta di kode.
  • Satu controller untuk semua peran; perbedaan akses ditangani scope dan Policy, bukan percabangan.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
spatie/laravel-permission 8.x
MySQL 8.4 LTS
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya