mmtech/iam-rbac

Portable RBAC module for Laravel microservices using Kafka snapshots with IAM fallback.

v1.10 2026-05-15 02:51 UTC

Requires

• php: ^8.3
• laravel/framework: ^12.0|^13.0
• mateusjunges/laravel-kafka: ^2.11

Requires (Dev)

• phpunit/phpunit: ^11.0

proprietary

README

Portable RBAC package for Laravel microservices.

What it provides

• Permission checks by gateway sub with request()->user()->can('permission.slug')
• Effective roles from the same snapshot with request()->user()->rbacRoles() / rbacRole() (or request()->rbacRoles())
• Kafka snapshot consumer (iam.rbac.snapshots.v1) always enabled in the command worker
• Reusable Kafka publisher service to emit events to any topic
• Multi-topic consumer with per-topic handlers (class-map)
• Local materialized store in database (rbac_user_permission_snapshots) with permissions and per-surface roles (id + name)
• IAM fallback endpoint support when local snapshot is missing

Installation in a Laravel microservice

1) Require package (private repository)

In the microservice install:

composer require mmtech/iam-rbac:^1.0

2) Publish package files

php artisan vendor:publish --tag=rbac-config
php artisan vendor:publish --tag=rbac-migrations
php artisan migrate --no-interaction

3) Register middleware aliases

In bootstrap/app.php:

$middleware->alias([
    'rbac.auth.user' => \Mmtech\Rbac\Http\Middleware\ResolveGatewayUserInfo::class,
    'rbac.bind.gateway.user' => \Mmtech\Rbac\Http\Middleware\BindGatewayUserToAuth::class,
]);

4) Configure env

RBAC_KAFKA_ENABLED=true
KAFKA_BROKERS=kafka.mmtech-solutions.com:9092
KAFKA_SECURITY_PROTOCOL=PLAINTEXT
RBAC_KAFKA_GROUP_ID=rbac-materializer
RBAC_KAFKA_ON_UNHANDLED_TOPIC=skip

RBAC_IAM_FALLBACK_ENABLED=true
RBAC_IAM_BASE_URL=http://iam-service
RBAC_IAM_INTERNAL_TOKEN=secret
RBAC_IAM_TIMEOUT_MS=1500

RBAC_FAIL_MODE=deny
RBAC_STRICT_DENY=true
RBAC_GATEWAY_INTERNAL_SECRET=apisix

The package publishes config/rbac.php and also publishes config/kafka.php from mateusjunges/laravel-kafka in the same rbac-config tag. This keeps Kafka connection config and RBAC module config clearly separated.

5) Run consumer

php artisan rbac:consume-snapshots

By default, the command first performs an initial sync (consume until last available message in Kafka for the consumer group) and then stays running to process future events. It always subscribes iam.rbac.snapshots.v1 and will additionally subscribe to any topics configured in rbac.consumer.handlers.

Optional flags:

• --skip-initial-sync: starts directly in continuous consume mode.
• --stop-after-last-message: run one catch-up pass and stop.

Multi-topic handlers (custom microservice logic)

In your microservice, implement handlers that process business logic for a topic:

<?php

namespace App\Kafka\Handlers;

use Junges\Kafka\Contracts\ConsumerMessage;
use Mmtech\Rbac\Kafka\Contracts\TopicMessageHandlerInterface;

final class AuthEventsTopicHandler implements TopicMessageHandlerInterface
{
    public function topic(): string
    {
        return 'auth.events.v1';
    }

    public function handle(ConsumerMessage $message): void
    {
        // Your business logic here.
    }
}

Register topic => handler class in published config/rbac.php:

'consumer' => [
    // ...
    'handlers' => [
        'auth.events.v1' => \App\Kafka\Handlers\AuthEventsTopicHandler::class,
    ],
],

Publish events from business logic

Inject Mmtech\Rbac\Kafka\KafkaEventPublisher and publish to any topic:

$publisher->publish(
    topic: 'notifications.email.v1',
    payload: ['event' => 'welcome-email', 'user_id' => $userId],
    key: $userId
);

Checking permissions with can()

The package registers a global Gate::before (RbacModule) so any can('permission.slug') call is resolved against the materialized snapshot (and IAM fallback when configured), not against Spatie models in this service.

Requirements

1. Run rbac:consume-snapshots (or otherwise have rows in rbac_user_permission_snapshots) so permissions exist for the user’s sub and surface.
2. On HTTP routes, use the gateway stack in order: validate gateway headers, bind the user, then authorize.

Surface is chosen the same way for every check: SurfaceResolver uses config('rbac.surface.default') when set; otherwise URLs whose path contains /admin use admin_panel, everything else customer_app.

Route middleware

Apply the middleware aliases, then Laravel’s can: middleware. The user must be a GatewayUser (after rbac.bind.gateway.user).

use Illuminate\Support\Facades\Route;

Route::middleware(['rbac.auth.user', 'rbac.bind.gateway.user', 'can:orders.read'])
    ->get('/orders', [OrdersController::class, 'index']);

If the snapshot does not include orders.read for that user and surface, Laravel returns 403. With rbac.auth.strict_deny enabled (default), unknown abilities are denied here instead of falling through to other gates.

In a controller or action

Use the authenticated user (or Gate) like any Laravel app; the package intercepts the ability name:

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

public function index(Request $request): JsonResponse
{
    abort_unless($request->user()->can('orders.read'), 403);

    return response()->json(['ok' => true]);
}

Equivalent checks:

auth()->user()->can('orders.read');
Gate::forUser($request->user())->allows('orders.read');
$this->authorize('orders.read'); // in a `Controller` using `AuthorizesRequests`

Programmatic check by sub (no HTTP user)

use Mmtech\Rbac\Authorization\Contracts\PermissionCheckerInterface;

$allowed = app(PermissionCheckerInterface::class)->userCan(
    $sub,
    'orders.read',
    'customer_app'
);

If you omit the third argument, the checker uses config('rbac.surface.default') or falls back to customer_app; it does not inspect the URL path (unlike Gate during an HTTP request, which uses SurfaceResolver). Pass the surface explicitly when mirroring HTTP behavior from jobs or CLI.

use Mmtech\Rbac\Authorization\Contracts\PermissionCheckerInterface;
use Mmtech\Rbac\Support\SurfaceResolver;

$allowed = app(PermissionCheckerInterface::class)->userCan(
    $sub,
    'orders.read',
    SurfaceResolver::resolve($request)
);

Reading effective roles

After rbac.bind.gateway.user, the authenticated user is a Mmtech\Rbac\Auth\GatewayUser. Roles come from the same materialized snapshot (and IAM fallback) as can(), using the current request surface (SurfaceResolver).

$roles = auth()->user()->rbacRoles(); // list<array{id: string, name: string}>
$first = auth()->user()->rbacRole();  // first entry or null

// Optional explicit surface (otherwise same as Gate / SurfaceResolver for this request):
$rolesAdmin = auth()->user()->rbacRoles('admin_panel');

// Request helpers (when user is GatewayUser):
$roles = request()->rbacRoles();
$first = request()->rbacRole();

You can also resolve roles by sub without a gateway user: app(\Mmtech\Rbac\Authorization\Contracts\PermissionCheckerInterface::class)->userRoles($sub, $surface).