Skip to content
rw3iss Auth

auth-server-laravel overview

rw3iss/auth-server-laravel is a thin Laravel adapter over auth-server-php. Wraps it in a custom Guard that verifies JWTs locally, role/permission/app middleware, a VenAuth Facade, Blade directives, and a HasVenAuth trait you drop onto your existing User model.

Sourcerw3iss/auth-server-laravel
StackPHP 8.1+ · Laravel 11+ · auto-discovered service provider
Wrapsauth-server-php
Mirrorauth-server-nest

The 80% usage

Terminal window
composer require rw3iss/auth-server-laravel
php artisan vendor:publish --tag=vauth-config
AUTH_SERVER_URL=https://auth.ryanweiss.net
JWT_ACCESS_SECRET=<shared with auth-server>
AUTH_APP_CODE=marketplace-buyer
config/auth.php
'guards' => ['web' => ['driver' => 'rw3iss-jwt', 'provider' => 'users']],
'providers' => [
    'users' => ['driver' => 'rw3iss', 'model' => \App\Models\User::class],
],
app/Models/User.php
use rw3iss\AuthServer\Laravel\Concerns\HasVenAuth;


class User extends Authenticatable {
    use HasVenAuth;
}
routes/web.php
Route::middleware('vauth')->group(function () {
    Route::get('/me', fn() => auth()->user());


    Route::middleware('vauth.role:org_admin,system_admin')
        ->get('/admin/users', AdminUsersController::class);


    Route::middleware('vauth.permission:listings:create')
        ->post('/listings', CreateListingController::class);
});

Middleware aliases

AliasPurpose
vauthValidate the bearer; populate auth()->user().
vauth.role:r1,r2Require any of the listed roles.
vauth.permission:p1,p2Require any of the listed permissions.
vauth.app:code1,code2Require the token’s app_id claim to match.
vauth.org:slug-or-idRequire the token’s org_id to match.
vauth.no_impRefuse impersonated tokens — for sensitive routes.

The facade

use rw3iss\AuthServer\Laravel\Facades\VenAuth;


$user = VenAuth::user();
$canEdit = VenAuth::hasPermission('listings:edit');
$isInOrg = VenAuth::hasOrg($orgId);
$isImpersonating = VenAuth::isImpersonating();

Blade directives

@vauth
    <a href="/profile">Profile</a>
@endvauth


@vrole('org_admin')
    <a href="/admin">Admin</a>
@endvrole


@vperm('listings:create')
    <button>New listing</button>
@endvperm


@vapp('marketplace-buyer')
    {{-- buyer-only UI --}}
@endvapp


@vimpersonating
    <div class="banner">You are impersonating {{ auth()->user()->email }}</div>
@endvimpersonating

The trait

HasVenAuth adds helpers to your User model so existing code (Eloquent relations, gates, policies) keeps working:

$user->hasVenRole('org_admin');
$user->hasVenPermission('listings:edit');
$user->venOrgId();
$user->venAppCode();

Two integration patterns

  • Pattern A — stateless. No local users table. auth()->user() returns the principal directly. Use when the Laravel app is purely a token-validating API server.
  • Pattern B — composable. Local users table referenced by rw3iss_id. The guard hydrates the model on each request. Use when you have local user-scoped data (preferences, profile, etc.).

config/vauth.php controls the pattern.

Session apps (Filament): the SSO bridge

Both patterns above assume bearer tokens. Session-based stacks — Filament panels, classic Blade — instead use the package’s SSO bridge: the app federates authentication to the auth-server (password + social SSO with PKCE) but keeps its native Laravel session, hydrating a local shadow user keyed to the core user id (ven_user_id) and logging it into an ordinary session guard. Opt in with AUTH_BRIDGE_ENABLED=true + one link column.

Full guide: SSO bridge (Filament).