Download the PHP package mmtech/iam-rbac without Composer

MMT IAM RBAC package

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:

2) Publish package files

3) Middleware aliases

The package registers these aliases automatically when RbacServiceProvider boots:

You may still declare custom names in bootstrap/app.php if needed (e.g. map auth.user to ResolveGatewayUserInfo).

4) Configure env

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

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:

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

Publish events from business logic

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

IAM user profile enrichment (rbac.auth.user.info)

After rbac.auth.user decodes gateway X-Userinfo, this middleware calls MMT-AUTH-SERVICE (GET /api/iam/v1/rbac/admin/users/{uuid} by default) using internal MS headers (X-Internal-Token, X-Internal-Source), merges the IAM data payload into gateway_auth_user_info, and rbac.bind.gateway.user exposes it on auth()->user() as GatewayUser (gatewayUserInfo, magic properties like country_id, email).

Middleware order:

If IAM is unreachable, RBAC_IAM_USER_FAIL_OPEN=true (default) keeps gateway-only claims; when false, the middleware responds with 502.

Internal service-to-service auth

Microservices can call each other without gateway user headers using a shared secret and a caller identity for access logs.

Headers (outbound from this MS):

IamFallbackClient sends the same headers when calling IAM internal RBAC endpoints.

Route patterns — always put rbac.trusted.internal first:

When X-Internal-Token is sent, X-Internal-Source is required (empty or missing → 403).

Request helpers for logging:

Laravel’s built-in can:foo middleware does not bypass for internal calls. Use rbac.authorize.or.internal:foo instead.

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 (and rbac.trusted.internal first when supporting MS-to-MS): validate gateway headers, enrich IAM profile when needed (rbac.auth.user.info), 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).

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:

Equivalent checks:

Programmatic check by sub (no HTTP user)

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.

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).

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