SessionBridge

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

The SSO bridge — lets a session-based Laravel app (Filament panels, classic Blade) federate authentication to the central rw3iss auth-server while keeping its own native session + Eloquent user.

Pattern (AUTH-PHP-LARAVEL-DESIGN.md §3.11 + the hybrid-backend decision): the auth-server owns credentials, social login, 2FA, rate limiting, and the core user record (in the app’s configured user pools — e.g. claimleo writes default+claimleo); this bridge hydrates a LOCAL shadow user keyed to the core user id and logs it into the ordinary Laravel session guard. Filament never knows the difference.

Three entry points:

• {@see loginWithPassword()} — drop-in for a login form’s authenticate step (e.g. a Filament Login page override). The form stays in the app; the credential check happens centrally.
• {@see ssoRedirectUrl()} + {@see completeSso()} — the browser redirect flow for social providers (Google, Apple, …), PKCE end-to-end. Used by {@see \rw3iss\AuthServer\Laravel\Http\SsoBridgeController}.
• {@see establish()} — the shared tail: decode the access token locally, resolve the shadow user, regenerate + log in.

The auth-server token pair survives in the Laravel session (via {@see LaravelSessionStore}) so the app can call the auth-server on behalf of the user afterwards (profile edits, org switching, …).

Methods

__construct()

function __construct(
    private readonly AuthClient $client,
    private readonly ResolvesShadowUser $resolver,
    private readonly AuthFactory $auth,
    private readonly Session $session,
    private readonly array $options = [],
)

Parameters

• $options — array{ guard?:string|null, remember?:bool, redirect_after_login?:string, }

loginWithPassword()

function loginWithPassword(
    string $email,
    string $password,
    bool $remember = false,
    ?string $twoFactorCode = null,
): ?Authenticatable

Password login against the auth-server, then establish the local session. Returns the logged-in local user, or null when the account requires a TOTP code (requires_2fa) — re-call with $twoFactorCode populated.

Throws

• InvalidCredentialsException wrong email/password (or the user isn't in this app's read pools — indistinguishable by design)
• ShadowUserDenied no local account and provisioning is off

ssoRedirectUrl()

function ssoRedirectUrl(
    string $provider,
    string $callbackUrl,
    ?string $next = null,
): string

Begin the social-SSO redirect: asks the auth-server for the provider auth URL (PKCE challenge attached; verifier parked in the Laravel session), remembers the provider + post-login destination, and returns the URL to redirect the browser to.

completeSso()

function completeSso(string $code, string $state): array

Finish the social-SSO callback: exchange code+state (PKCE) for tokens at the auth-server, then establish the local session.

Returns

• array{user:Authenticatable, next:string|null}

establish()

function establish(AuthResponse $response, bool $remember = false): Authenticatable

Shared tail for every federated login: decode the access token locally (HS256 — no extra network hop), hand the principal to the shadow-user resolver, then rotate the session id and log the local user into the configured guard.

logout()

function logout(): void

Log out both halves: the Laravel session guard AND the auth-server refresh chain (best-effort — a dead auth-server must not trap the user in a session).

defaultRedirect()

function defaultRedirect(): string

Default post-login destination (config bridge.redirect_after_login).