25 - Tenant Authorization Backend Guide

Dokumen ini adalah panduan teknis lengkap untuk authorization (authz) di konteks tenant pada backend.

Tujuan

Menjelaskan arsitektur authz tenant yang berjalan saat ini.

Menjadi referensi implementasi fitur baru agar konsisten dengan pola existing.

Menjadi single technical guide untuk:

route-level authorization,

role/permission management,

lifecycle role system (Owner, Guest),

seeding default RBAC tenant.

1. Komponen Utama

1.1 Config (source of truth)

config/tenant_authz.php

enabled

allow_unmapped_routes

permissions (katalog permission)

default_role_permissions (guest, member, dst)

route_permissions (mapping route name ke permission)

1.2 Middleware & Resolver

App\Http\Middleware\Tenant\Authz\EnforceTenantRoutePermission

App\Services\Tenant\Authz\TenantRoutePermissionResolver

App\Services\Central\Auth\AuthorizationResolver

1.3 Authz API Domain

App\Http\Controllers\Api\V1\Tenant\Authz\RoleController

App\Services\Tenant\Authz\TenantRolePermissionService

App\Services\Tenant\Authz\TenantRoleLifecycleService

1.4 Seed & Model Pivot

Database\Seeders\RolePermissionSeeder

Pivot models:

App\Models\Tenant\Authorization\RoleHasPermission

App\Models\Tenant\Authorization\ModelHasRole

App\Models\Central\Authorization\RoleHasPermission

App\Models\Central\Authorization\ModelHasRole

2. Flow Authorization per Request (Tenant API)

Detail penting

Owner tenant di-bypass middleware (akses endpoint tenant tidak dibatasi route map).

Matching permission mendukung fallback kandidat:

exact (group.resource.action)

short form (resource.action)

manage implied untuk action non-manage.

tenant_authz_permissions disimpan di request attributes untuk menghindari resolve berulang.

3. Resolve Permission User

AuthorizationResolver mengambil roles & permissions dari cluster tenant:

role dari model_has_roles + roles

direct permission dari model_has_permissions + permissions

inherited permission dari model_has_roles + role_has_permissions + permissions

Output normalize:

Untuk platform context (resolvePlatform), sumber data dari central RBAC.

4. Route-Level Mapping

TenantRoutePermissionResolver bekerja dengan route name (bukan path literal):

exact key: tenant.user.index

wildcard key: tenant.billing.*

value bisa:

string tunggal

array (ANY-of)

Contoh:

5. Role & Permission Management (Tenant Authz APIs)

5.1 RoleController

index: list role + permission.

store: buat role custom (is_system=false).

update: dilarang untuk role system.

destroy: dilarang untuk role system, lalu lifecycle delete via service.

5.2 TenantRolePermissionService

Fokus permission concern:

validasi permission ids

validasi role ids (dengan opsi tolak is_system)

sync role-permission

hydrate role-permission

sync role user tenant

attach role ke tenant user list

sync default permission untuk Guest system role

5.3 TenantRoleLifecycleService

Fokus lifecycle role:

hapus role custom

fallback auto-assign role Guest untuk user terdampak yang tidak punya role lain

memastikan Guest ada dan selalu is_system=true

6. System Roles dan Rules

6.1 Owner

is_system=true

tidak bisa diupdate/dihapus via role API

memiliki akses route-level bypass pada middleware tenant authz

6.2 Guest

is_system=true

role fallback default saat role custom dihapus

permission sinkron dari:

tenant_authz.default_role_permissions.guest

6.3 Member

default non-system role

permission sinkron dari:

tenant_authz.default_role_permissions.member

7. Seeder Strategy (`RolePermissionSeeder`)

Seeder saat ini:

menggunakan katalog permission dari tenant_authz.permissions

memvalidasi referensi permission dari:

route_permissions

default_role_permissions.member

default_role_permissions.guest

create/update role sistem:

Owner (system)

Guest (system)

Member (non-system)

sync pivot role-permission dan model-has-role via model Eloquent pivot.

Catatan:

Seeder ini idempotent (updateOrCreate + sync pattern).

Jika menambah permission baru, jalankan seeder ulang agar default role sinkron.

8. Cara Menambah Fitur Baru (Checklist Praktis)

8.1 Tambah endpoint tenant baru

Tambah permission baru di tenant_authz.permissions.

Mapping route name endpoint ke permission di tenant_authz.route_permissions.

(Opsional) tambahkan ke default role set (member/guest) bila perlu.

Jalankan seeder.

Tambah/ubah test middleware route permission.

8.2 Tambah menu/halaman FE baru

Selaraskan permission FE dengan naming backend.

Mapping path -> permission di sidebar/route guard FE.

Pastikan GET /auth/me mengandung permission yang dibutuhkan.

8.3 Tambah object-level rule

Route-level middleware tidak cukup untuk rule per record/state.
Implementasikan di service/policy/controller, contoh:

larang edit role sendiri

larang ubah owner

larang assign role system ke employee

9. Testing Matrix Minimal

9.1 Route-level

mapped route + user punya permission => 200

mapped route + user tidak punya permission => 403

unmapped route + allow_unmapped=true => pass

unmapped route + allow_unmapped=false => 403

9.2 Role lifecycle

update/destroy role system => 403

destroy role custom => user fallback ke Guest jika kehilangan semua role

9.3 User-role assignment

assign role system ke tenant user => 422

non-owner tidak bisa ubah role dirinya sendiri (jika rule aktif)

10. Operasional & Troubleshooting

Gejala: user tiba-tiba 403 di endpoint tenant

Periksa:

route name endpoint sudah dimapping di route_permissions?

permission user ada di payload auth/me?

membership user aktif di tenant?

tenant_authz.enabled bernilai true/false sesuai ekspektasi?

allow_unmapped_routes tidak menutup endpoint baru?

Gejala: permission baru tidak berefek

Periksa:

config sudah ter-load (php artisan config:clear jika perlu).

role/permission seed sudah dijalankan ulang.

data role assignment tenant user sudah benar.

11. Referensi Kode

Middleware:

app/Http/Middleware/Tenant/Authz/EnforceTenantRoutePermission.php

Route resolver:

app/Services/Tenant/Authz/TenantRoutePermissionResolver.php

Authorization resolver:

app/Services/Central/Auth/AuthorizationResolver.php

Authz services:

app/Services/Tenant/Authz/TenantRolePermissionService.php

app/Services/Tenant/Authz/TenantRoleLifecycleService.php

Controller:

app/Http/Controllers/Api/V1/Tenant/Authz/RoleController.php

Config:

config/tenant_authz.php

Seeder:

database/seeders/RolePermissionSeeder.php

Tests:

tests/Feature/Tenant/Authz/TenantRoutePermissionMiddlewareTest.php

tests/Feature/Tenant/Authz/TenantRoleApiTest.php

tests/Feature/Tenant/Identity/TenantUserApiTest.php

12. Ringkasan

Tenant authz backend sudah memakai pola layered:

config-driven permission catalog & route mapping,

middleware guard untuk endpoint-level,

service lifecycle untuk business rule role system,

fallback Guest untuk menjaga konsistensi akses user setelah mutasi role.

Pola ini membuat penambahan fitur baru cukup predictable:

update config,

update seed,

update route/menu mapping,

tambah test.

25 - Tenant Authorization Backend Guide

Tujuan#

1. Komponen Utama#

1.1 Config (source of truth)#

1.2 Middleware & Resolver#

1.3 Authz API Domain#

1.4 Seed & Model Pivot#

2. Flow Authorization per Request (Tenant API)#

Detail penting#

3. Resolve Permission User#

4. Route-Level Mapping#

5. Role & Permission Management (Tenant Authz APIs)#

5.1 RoleController#

5.2 TenantRolePermissionService#

5.3 TenantRoleLifecycleService#

6. System Roles dan Rules#

6.1 Owner#

6.2 Guest#

6.3 Member#

7. Seeder Strategy (RolePermissionSeeder)#

8. Cara Menambah Fitur Baru (Checklist Praktis)#

8.1 Tambah endpoint tenant baru#

8.2 Tambah menu/halaman FE baru#

8.3 Tambah object-level rule#

9. Testing Matrix Minimal#

9.1 Route-level#

9.2 Role lifecycle#

9.3 User-role assignment#

10. Operasional & Troubleshooting#

Gejala: user tiba-tiba 403 di endpoint tenant#

Gejala: permission baru tidak berefek#

11. Referensi Kode#

12. Ringkasan#