Filament Authz

A comprehensive Filament v5 authorization package extending Spatie laravel-permission with wildcard permissions, multi-panel support, and automatic entity discovery.

Features

• Super Admin Bypass — Configure a role that automatically bypasses all permission checks via Gate::before
• Wildcard Permissions — Support for patterns like orders.* to match orders.view, orders.create, etc.
• Role & Permission Resources — Clean Filament UI for managing roles and permissions with tabbed interface
• Automatic Discovery — Discovers Resources, Pages, and Widgets to generate permissions automatically
• Multi-Panel Support — Configure different authorization settings per Filament panel
• Policy Generation — CLI command to scaffold Laravel Policies based on discovered permissions
• Authz Scopes + Tenant Scoping — Scope roles to any model (institutions, speakers, etc.) with central app support and optional commerce-support integration
• UUID-First Schema — Uses the UUID-backed migrations provided by the aiarmada/authz core package

Requirements

• PHP 8.4+
• Laravel 13+
• Filament 5.0+
• Spatie laravel-permission 8.0+

Installation

composer require aiarmada/filament-authz

Publish the configuration:

php artisan vendor:publish --tag=filament-authz-config
php artisan vendor:publish --tag=authz-config

Run migrations:

php artisan migrate

The required authz package ships UUID-based migrations for Spatie Permission tables (permissions, roles, model_has_permissions, model_has_roles, and role_has_permissions) plus the authz_scopes migration. filament-authz owns the Filament UI and does not ship database migrations. The schema, models, and pivot keys are all UUID-based together.

Setup

Add HasRoles Trait

Add the HasRoles trait to your User model:

use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
}

Register Plugin

use AIArmada\FilamentAuthz\FilamentAuthzPlugin;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentAuthzPlugin::make(),
        ]);
}

Configuration

// config/filament-authz.php
return [
    // Scope roles and permissions to a tenant/scope (Spatie teams)
    'scoped_to_tenant' => true,

    // Allow managing roles across scopes in a central panel
    'central_app' => false,

    'role_resource' => [
        'scope_options' => null,
    ],

    'user_resource' => [
        'form' => [
            'role_scope_mode' => 'all', // all, global_only, scoped_only
        ],
    ],

    // Navigation settings
    'navigation' => [
        'group' => 'Authz',
        'sort' => 99,
    ],

];

Configure the shared authentication guard list in config/authz.php under authz.guards. It is consumed by both core commands and the Filament UI.

Core authorization settings live in config/authz.php:

return [
    'super_admin_role' => 'super_admin',
    'wildcard_permissions' => true,
    'scopes' => [
        'enabled' => false,
        'auto_create' => true,
        'enforce' => true,
    ],
    'permissions' => [
        'separator' => '.',
        'case' => 'camel',
    ],
    'custom_permissions' => [],
];

Usage

Permission Macros

use Filament\Actions\Action;

// Require a specific permission
Action::make('export')
    ->requiresPermission('order.export');

// Require a role
Action::make('admin-settings')
    ->requiresRole('Admin');

// Require any of multiple roles
Action::make('analytics')
    ->requiresRole(['Admin', 'Analyst']);

// Require any of multiple permissions
Action::make('reports')
    ->requiresAnyPermission(['report.view', 'report.export']);

Wildcard Permissions

// Grant 'orders.*' to a role
$role->givePermissionTo('orders.*');

// This now passes for any 'orders.X' check
$user->can('orders.view');   // true
$user->can('orders.create'); // true
$user->can('orders.delete'); // true

Super Admin Bypass

Users with the configured super admin role automatically bypass all permission checks:

// User with 'super_admin' role passes all gates
Gate::allows('any-permission'); // true

Authz Scopes (Optional)

Use Authz scopes to attach roles/permissions to any model (institutions, speakers, events, etc.).

// config/authz.php
'scopes' => [
    'enabled' => true,
    'auto_create' => true,
],

// config/permission.php
'teams' => true,
'team_foreign_key' => 'authz_scope_id',

use AIArmada\Authz\Concerns\HasAuthzScope;
use AIArmada\FilamentAuthz\Facades\FilamentAuthz;

class Workspace extends Model
{
    use HasAuthzScope;
}

FilamentAuthz::userCanInScope($user, 'project.update', $workspace);

Limiting Role Scope Options

If your central panel should only expose a subset of scopes in the Role resource, provide an explicit options map.

use AIArmada\FilamentAuthz\FilamentAuthzPlugin;

FilamentAuthzPlugin::make()
    ->roleScopeOptionsUsing([
        'scope-id-1' => 'Team Members',
        'scope-id-2' => 'Support Team',
    ]);

Or through config:

'role_resource' => [
    'scope_options' => [
        'scope-id-1' => 'Team Members',
        'scope-id-2' => 'Support Team',
    ],
],

Restricting User Role Editing By Scope

The User resource can expose:

• all
• global_only
• scoped_only

FilamentAuthzPlugin::make()
    ->userRoleScopeMode('global_only');

Or through config:

'user_resource' => [
    'form' => [
        'role_scope_mode' => 'global_only',
    ],
],

Related core commands

The authz core package owns the shared authorization commands below:

Sync Permissions

Sync roles and permissions from configuration:

php artisan authz:sync

Permission Naming Convention

Use {resource}.{ability} format:

License

MIT License. See LICENSE for details.