Laravel Sso Laravel Package

Getting Started

1. composer require postiefs/laravel-sso
2. php artisan sso:install — publishes the config and scaffolds the pieces the package needs (routes, guard/middleware wiring, .env keys for the portal URL, client id/audience and HS256 signing secret).
3. php artisan sso:check — run this immediately after install. It is the fastest way to confirm the portal is reachable, the issuer/audience/secret are correct, and that your Callback URL matches what the portal has registered.
4. Read the config file before anything else, then the docs/ folder. Two knobs matter day-to-day: the portal connection settings and check_interval (how often /auth/check-access is called).

First use case: protecting an existing app area with portal identity instead of local passwords.

Route::middleware('sso.auth')->group(function () {
    Route::get('/dashboard', DashboardController::class);
});

Point users at the package's login route, let callback exchange the launch token, and let the shipped UserResolver find-or-create a user by email. From there, replace any Auth::attempt() in your login controller with a redirect to the SSO login route — the local password path should go away entirely, not live alongside it.

Implementation Patterns

Route protection is three middlewares, not one. Treat them as a stack with distinct meanings and verify the exact semantics in the docs before mixing them:

Put your own authorization middleware after sso.auth, and keep package middleware ahead of anything that touches Auth::user().

Customise identity with UserResolver. The default finds-or-creates by email and never mutates an existing user. The moment you need a different lookup key (employee number, tenant-scoped email) or extra provisioning (default team, locale, profile sync), bind your own implementation in a service provider. This is the single most important extension point — most real apps will override it.

Do the "never changes an existing user" work yourself. Because the default resolver leaves existing records alone, profile drift (name changes, department moves) will not self-heal. Hook SsoUserCreated for first-time provisioning and handle updates explicitly, either in your resolver or from SsoLoggedIn:

Event::listen(SsoUserCreated::class, function ($event) {
    $event->user->assignRole('member'); // spatie/laravel-permission, etc.
});

Event::listen(SsoLoggedIn::class, function ($event) {
    $event->user->update(['name' => $event->claims['name'] ?? $event->user->name]);
});

Roles staying in your app is deliberate — the package adds no columns and no migrations, so your permission model is untouched. Seed default roles on SsoUserCreated rather than in a migration.

Handle session end explicitly. SsoSessionEnded fires when the portal ends the session; pair it with the ended route so your UI lands somewhere sensible instead of a bare 401. Use it for audit logging and cache/impersonation invalidation.

Use @ssoSessionGuard in your layout, once. Drop it into the authenticated layout (not per-page) so the deadline timer and heartbeat are present on every screen. Without it, the browser will not proactively sign out at the sexp deadline or send heartbeats — the server-side check still applies, but the UX degrades to surprise redirects.

Reach for the Sso facade for read-only session facts (current deadline, remaining time) when rendering a "signed in until…" indicator or gating a long-running action.

Testing: LaunchToken lets you mint tokens in feature tests without a browser round-trip to the portal. Combine it with actingAs() for everything downstream of the callback, and stub/short-circuit the portal check so tests never hit the network. Assert on the events rather than on package internals.

Gotchas and Tips

• The deadline is absolute and never extended. sexp is adopted as-is. A user editing a long form or uploading a large file will be signed out mid-flight. Design for it: warn near the deadline, save drafts, and make the post-expiry redirect preserve the intended destination.
• check_interval is your revocation latency budget. Portal downtime deliberately fails open (users stay signed in). That is the right trade-off, but it means a revoked user survives until the next successful check — plus up to check_interval of slack. Keep it short enough to matter to security, long enough not to hammer the portal from every open tab.
• Fail-open means outages hide problems. Add monitoring or a log alert on failed /auth/check-access responses; otherwise a broken portal integration looks like normal operation.
• A "stray token" almost always means a Callback URL mismatch. The package logs and forwards instead of throwing. When debugging "why is this user signed in as someone else" or "why did the token get consumed", check the logs for stray-token entries and compare the registered Callback URL against your actual route first.
• Launch tokens are single use. Back-button and double-submit on the callback will fail the second time. Make the callback error state recoverable (restart login) rather than a dead end.
• Email is the default identity key — normalise it. No migrations means no schema-level uniqueness guarantee from the package. Pre-existing local users with casing or alias differences will not be matched and a duplicate account will be created. Lowercase/trim email in a custom resolver, or key on something stable like the Entra object id.
• HS256 secret rotation is a coordinated deploy. A mismatch produces token verification failures across the board — issuer/audience/expiry checks fail with it. Rotate on both sides together; sso:check is your post-deploy smoke test.
• Expiry checks are clock-sensitive. Session deadlines and token expiry both depend on accurate server time; keep NTP healthy on app servers or users get spurious sign-outs.
• Local development will not round-trip through the portal without a public URL/tunnel. Lean on LaunchToken locally instead of trying to make the redirect work on localhost.
• Config changes need php artisan config:cache re-run in cached environments, especially check_interval — it is easy to change in .env and see no effect.
• Don't keep a parallel local login. Two entry points means two session lifetimes and two revocation stories, and the portal-controlled deadline silently stops applying to half your users.