Laravel Sso Client Laravel Package

Technical Evaluation

Architecture fit: This is a thin Laravel SSO client that pairs with laravel-sso-server. Release 1.1.0 tightens the coupling between the two: federated logout requires server 1.1+, and the email_verified claim changes account-linking semantics. It remains a conventional Laravel package — routes, config, middleware — so it fits any standard Laravel app without architectural change. The main new architectural surface is the logout flow, which now leaves the app (browser redirect to the server) and depends on server-side session termination to be effective.

Integration feasibility: Straightforward for a fresh install. For existing installs it is a config-and-UI change, not a code rewrite:

• Add 'logout' => '/sso/logout' to endpoints and set post_logout_redirect_uri if the config was published before 1.1.0.
• Change logout buttons from GET links (or Auth::logout()) to POST route('sso-client.logout').
• Requires the SSO server to be upgraded to 1.1+ for true federated logout.

The email_verified change is opt-in-by-default in the sense that servers not emitting the claim retain 1.0 behavior; but any server that does emit it will see different linking outcomes immediately.

Technical risk:

• Token handling (highest): the access token is passed to the server as a token_hint on a redirect. If that is a query parameter, it is exposed to browser history, referrer headers, proxy/access logs, and any monitoring that captures URLs. Needs confirmation that it is a POST body, a short-lived opaque handle, or otherwise non-replayable.
• Version skew: the client advertises server 1.1+ support but silently degrades (local-only logout) against older servers or for users who signed in pre-upgrade. That is a graceful failure, but it means federated logout will not work for a subset of users until they re-authenticate — a support-ticket generator if not communicated.
• Behavior change in account linking: refusing existing users with unverified emails in legacy email-only mode is a lockout vector. Users who previously could sign in may be denied after deploy.
• Redirect origin enforcement: SSO_POST_LOGOUT_REDIRECT_URI must share an origin with the redirect URI; misconfiguration likely fails at runtime rather than at boot.
• Claim parsing: email_verified enforcement hinges on strict boolean interpretation. A server sending "true", 1, or "1" could be treated inconsistently.

Key questions:

1. Is token_hint transmitted as a POST body or a query string, and is it single-use / short-lived?
2. Where is the access token stored between login and logout, and is it encrypted at rest?
3. What is the exact failure behavior when SSO_POST_LOGOUT_REDIRECT_URI origin validation fails — boot-time exception or per-request error?
4. Does the email_verified check treat only literal true as verified, or does it coerce truthy values?
5. Is there a documented rollback path if the server is not yet on 1.1 (does the client fall back cleanly to local logout)?
6. What is the support policy — is client 1.1.x compatible with server 1.0.x, and for how long?

Integration Approach

Stack fit: Native Laravel. No new runtime dependencies beyond the existing package and a compatible server. Tested against PHP 8.4 / Laravel 13 across SQLite, MySQL and PostgreSQL, with interop tests against server 1.1.0 — that is a credible compatibility matrix for a package of this size. Teams on older Laravel/PHP should confirm the supported range before assuming parity with the tested matrix.

Migration path:

1. Upgrade laravel-sso-server to 1.1+ first (federated logout is inert without it).
2. Upgrade the client package.
3. Republish/merge config: add the logout endpoint and post_logout_redirect_uri.
4. Set SSO_POST_LOGOUT_REDIRECT_URI to a same-origin landing page (defaults to home).
5. Replace logout links with a CSRF-protected POST form/button targeting route('sso-client.logout').
6. Decide explicitly on link_existing_users_by_email and confirm the server emits email_verified.
7. Optionally adopt the Laravel Boost guideline and sso-client-development skill for AI-assisted work (developer-facing, no runtime impact).

Compatibility: The email_verified change is backward-compatible only for servers that do not send the claim. Servers that send it will change linking behavior at deploy time — this is the one item that should be treated as a coordinated release, not a routine patch. The logout change is not a breaking API change but is a breaking UX/route change for any template or bookmark that used a GET logout.

Sequencing: Server first, then client, then config, then UI. Do not flip email_verified enforcement and federated logout in the same deploy — separate the account-linking behavior change from the logout change so failures are attributable. Run staging with a server that emits email_verified: false for a test account before production.

Operational Impact

Maintenance: Low, but coupled. The client now has a hard functional dependency on server 1.1+ for federated logout, so upgrades should be planned as paired releases. The added config keys mean published configs drift; teams should diff against the package default on each upgrade. The Laravel Boost skill is a documentation artifact and adds negligible maintenance.

Support: Expect two clusters of tickets: (a) users who were signed in before the upgrade and only get local logout, and (b) users denied sign-in under the new email_verified rules. Both need pre-deploy comms and a documented answer. Also expect "logout didn't log me out of everything" reports from apps still on the older server.

Scaling: No meaningful change. Federated logout adds one browser redirect per logout — negligible load. The notable scaling consideration is correctness under multiple apps: federated logout is only as good as the server's back-channel notification, so the user-visible guarantee is "eventually logged out everywhere," not "atomically logged out everywhere."

Failure modes:

• Server unreachable during logout → user is logged out locally but not federated; silent partial logout.
• Token absent (pre-upgrade session or dropped token) → local-only logout, no error surfaced to the user.
• Misconfigured post_logout_redirect_uri origin → logout redirect fails after the local session is already destroyed; user lands on an error with no session to retry from.
• email_verified false or missing under legacy email-only mode → existing user locked out with no self-service path.
• Token leaked via redirect URL → session-replay risk if token_hint is a bearer credential in a query string.

Ramp-up: Low for a Laravel-fluent engineer — the package is config plus a route. The learning is not in the code but in the SSO model: understanding that logout is now a two-party flow, and that account linking is gated on a server-supplied claim. Budget half a day for the upgrade and UI change, plus a staging pass that specifically exercises unverified-email and pre-upgrade-session cases. The sso-client-development skill and guideline in resources/boost lower ramp-up further for teams using Laravel Boost.