ResolvesShadowUser

class rw3iss\AuthServer\Laravel\Bridge\ResolvesShadowUser src/Bridge/ResolvesShadowUser.php ↗

Maps a federated auth-server identity onto the app’s OWN user entity (the “shadow user”) so a session-based stack — Filament, classic Blade apps — keeps its native Eloquent user while the auth-server stays the source of truth for credentials, SSO, 2FA, roles, and the core user record.

Called by {@see SessionBridge} after every successful federated login (password or SSO), inside the request that establishes the Laravel session. Implementations should be idempotent:

1. find the local user linked to $principal->id (e.g. a ven_user_id column) — return it (optionally syncing email/name drift);
2. else adopt an existing local user with the same email — link it and return it;
3. else provision a fresh local row (or throw, for apps that provision out-of-band — see bridge.create_missing).

The default implementation is {@see EmailShadowUserResolver}; bind your own class in config/vauth.php (bridge.resolver) when the app needs custom role mapping or multiple user types (e.g. ClaimLeo’s staff User vs Homeowner models — one bridge per guard).

See also

• docs/SSO_BRIDGE.md

Methods

resolve()

function resolve(UserPrincipal $principal, array $user): Authenticatable;

Parameters

• $principal — UserPrincipal · decoded access-token claims (id, email, names, roles, permissions, namespace, …)
• $user — array<string,mixed> · the raw user object from the auth-server response (richer than the claims: status, avatar, metadata)

Returns

• Authenticatable the local user to log into the session

Throws

• ShadowUserDenied when the identity must not enter this app (e.g. provisioning is out-of-band and no local match exists)