Laravel Sso Laravel Package

Technical Evaluation

Architecture fit

This is a thin authentication adapter, not an identity system. It adds no tables, owns no roles, and delegates all user persistence to a UserResolver contract. That is the strongest architectural signal in the release: the package can be layered onto an existing users table, an existing RBAC setup (explicitly: spatie/laravel-permission), and existing policies without a schema change or backfill.

The flow is portal (Entra ID) → launch token → callback route → token verification → resolver → Laravel session with an absolute deadline derived from sexp. Sessions are portal-controlled and non-extendable.

Three middleware aliases (sso, sso.auth, sso.session) give three distinct enforcement points — initiate SSO, require an SSO session, enforce deadline/heartbeat. That maps cleanly onto route-group-level adoption and supports incremental rollout rather than a flag day.

The UserResolver contract is the only meaningful extension seam, and it is where the entire account-linking policy lives. Architecturally that is correct; operationally it means identity decisions are per-app and can diverge across the fleet unless someone owns a standard.

Integration feasibility

Low friction. composer require, sso:install, sso:check is about as cheap as Laravel onboarding gets, and shipping a diagnostic command with v1.0.0 is a genuine adoption accelerant — it turns "is my config right" into a command instead of a support ticket.

Zero migrations is a serious de-risker: no schema lock, no DBA review of data changes, no rollback plan, and security review is scoped to config plus secrets.

LaunchToken as a test helper and the SsoUserCreated / SsoLoggedIn / SsoSessionEnded events mean teams can write feature tests and wire audit logging without forking the package.

The one real front-end commitment is @ssoSessionGuard. It's trivial in Blade; it is an open question for Inertia/Livewire/SPA front-ends that don't render server-side Blade on every page.

Hard constraint: PHP 8.2+ and Laravel 11/12/13. Laravel 11 as the floor excludes Laravel 10 apps — the most likely blocker across an existing portfolio.

Technical risk

• Fail-open session checking. "If the portal is down, users stay signed in" is an explicit availability-over-revocation trade. Defensible, but it sets a revocation-latency ceiling of check_interval plus outage duration. Needs a documented sign-off and, ideally, a fail-closed option for privileged surfaces.
• HS256 shared secret. Symmetric signing means every integrating app holds a secret capable of minting tokens. Rotation, per-environment separation, and secret storage (vault vs .env) are unaddressed in these notes and are the top pre-production verification item.
• Single-use without migrations. Replay protection implies server-side state, but the release explicitly adds no tables. Where that state lives determines whether single-use actually holds across N app nodes and what happens on cache flush. Highest-severity open question.
• Email as identity key, non-mutating resolver. The default resolver "finds or creates by email and never changes an existing user." Consequences: profile drift from Entra ID never propagates, and an email change in the IdP creates a new local user instead of linking. Deprovisioning in Entra ID has no described local effect beyond session expiry.
• Absolute session deadline. No sliding sessions. Good compliance posture, predictable mid-work logout for long forms and uploads, and it requires a real "session ended" UX path.
• Stray token "logged and forwarded." A launch token at the wrong Callback URL is both a misconfiguration signal and a potential token-disclosure path. "Forwarded" needs a precise definition — destination, logging, and whether the token is invalidated.

Key questions

1. Where is single-use token state stored, and is it correct across multiple instances behind a load balancer?
2. What is the HS256 rotation story — dual-secret overlap window, or hard cutover with an outage?
3. Is check_interval configurable per app / route group, and can we opt into fail-closed?
4. Does the token or callback carry Entra ID role/group claims, or is all authorization strictly app-owned?
5. What happens to a "forwarded" stray token, and is it invalidated?
6. Is there RP-initiated or back-channel logout, or does the local session end only via sexp and the ended route?
7. What is the semver / deprecation / changelog contract going forward from v1.0.0?
8. Is there a supported path for non-Blade front-ends where @ssoSessionGuard isn't rendered per page?

Integration Approach

Stack fit

Good fit for conventional Laravel monoliths on Laravel 11+ with Blade-rendered authenticated areas. The package sits beside existing auth rather than replacing it, so apps can keep local login for service accounts, break-glass admins, or machine access while SSO covers human users. Authorization stays in the app, which is where most teams already want it. Poor fit where the app is Laravel 10, where the front-end is SPA-first with no server-rendered shell, or where a hard requirement exists for fail-closed session validation.

Migration path

The absence of migrations makes the migration path unusually cheap in both directions:

1. Pilot on one low-blast-radius internal app.
2. Add the sso middleware to a single route group; leave everything else on existing auth.
3. Point the default UserResolver at existing users, or supply a custom resolver if account linking must be stricter than email match.
4. Roll forward route group by route group.

Rollback is composer remove plus middleware removal — no schema to unwind, no data to reconcile. That is a legitimate selling point to risk committees and should be stated explicitly in the rollout plan.

Compatibility

• Laravel 13 support is declared at v1.0.0, before most estates have migrated to it. Verify this is tested in CI, not merely permitted in composer.json.
• Coexistence with Fortify/Breeze/Jetstream needs a decision: do SSO users keep a local password? If not, password reset and local login routes should be disabled for those accounts.
• Cache driver matters if single-use state is cache-backed — array/file drivers will behave differently from Redis in multi-node setups and in tests.
• Existing custom auth guards and multi-guard apps need a check that sso composes with them rather than replacing the default guard.

Sequencing

1. Confirm the constraint match (PHP/Laravel version) across target apps — do this first, it decides the scope.
2. Resolve the single-use state store and the secret-handling/rotation model before any code lands.
3. Decide the account-linking policy centrally: default email-match resolver vs custom resolver per app. Publish it.
4. Pilot one app end-to-end, including sso:check in CI and a runbook entry.
5. Design the session-ended UX (unsaved-work protection, re-auth prompt) before the first user-facing app.
6. Wire SsoSessionEnded and the check-failure path into existing logging/alerting.
7. Roll out route group by route group; only then consider making SSO the only human login.

Operational Impact

Maintenance

Very low surface area: no schema, no background jobs described, no scheduled tasks beyond sso:check as a manual or CI diagnostic. The package's real maintenance cost is configuration drift across apps — diverging resolver logic, divergent check_interval values, and diverging secret handling. Assign one owner for the shared policy and one for each app's resolver.

Support

Introduces a two-tier support boundary that must be explicit in the runbook: the portal/Entra ID team owns token issuance and availability; each app team owns resolver config and route wiring. sso:check should be tier-1's first diagnostic. Because v1.0.0 ships only a docs folder — no stated support SLA, changelog policy, or issue tracker commitment — the TPM should get a vendor support expectation in writing before this becomes load-bearing.

Scaling

Two cost centers. First, heartbeat and /auth/check-access traffic: at 10k concurrent users with check_interval = 300s, that's roughly 33 requests/second sustained against the portal, plus the same order of magnitude against your own endpoints. Shortening the interval for fresher revocation scales linearly and should be treated as a capacity decision, not a security knob to tune per app. Second, the single-use token store: it needs to be shared, fast, and durable enough that a flush doesn't open a replay window. Both need load testing at realistic concurrency before fleet rollout.

Failure modes

The asymmetry in the first row matters for the runbook: a portal outage looks like "everything is fine" to logged-in users and "nothing works" to anyone arriving fresh.

Ramp-up

For a single app on a supported Laravel version: roughly 1–2 engineer-days including resolver, tests via LaunchToken, and sso:check in CI. Add time for secret management integration, session-ended UX, and observability wiring — those are app-specific and will dominate the estimate on the first app. The second and subsequent apps should be well under a day if the linking policy is already standardized.