Sso Helper Laravel Laravel Package

Getting Started

1. Confirm you can install v4. The package now requires PHP 8.2+ and Laravel 10–13. If you're on PHP 8.1 or Laravel 8/9, you cannot upgrade — pin ^3.0 and plan the runtime upgrade separately:

composer require tekinfopg/sso-helper-laravel:^4.0

2. Look at the published config first. This is where 90% of the day-to-day behaviour lives. Publish it and read it top to bottom before writing any code:

php artisan vendor:publish --provider="Tekin\SsoHelper\SsoHelperServiceProvider" --tag=config

Then check php artisan vendor:publish with no arguments to see exactly which tags the package exposes (config, migrations, views) — the list is authoritative, don't guess. Inspect config/sso.php for the IdP base URL, client credentials, redirect/callback URIs, scopes, and the user model / attribute-mapping keys.

3. Wire up environment variables. Everything in the config file should be env-driven so local/staging/production point at different IdP tenants. Match the keys in config/sso.php, not the ones in your memory of v3.

4. See the routes it registers. Before writing controllers, run:

php artisan route:list | grep -i sso

You'll typically get a login/redirect route and a callback route. Knowing these exist saves you from hand-rolling a controller that the package already ships.

5. First use case: protect one route group. The smallest useful increment is putting the package's middleware (or auth + your configured SSO guard) on a single route and logging in through the IdP. Get one happy-path login working end-to-end — redirect out, callback in, session established, user visible via Auth::user() — before touching logout, refresh, or attribute mapping.

Implementation Patterns

Guard the app, don't re-implement auth. The idiomatic setup is a dedicated guard/driver plus middleware on your route group. Resist the pull to write your own callback controller; the package's callback handles state/nonce validation, and reimplementing it is where security bugs enter.

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

Just-in-time provisioning vs. pre-provisioned users. Decide early which model you're in:

• JIT: the callback resolves/creates a local User from SSO claims on first login. Convenient, but you must own the attribute-to-column mapping and handle claim changes (e.g. email changes at the IdP) without creating duplicate accounts.
• Pre-provisioned: users exist locally; SSO only authenticates. Safer for apps with local roles/permissions. Make sure the lookup key (email, sub, employee ID) is immutable at the IdP — email is usually the wrong choice.

Keep authorization local. Use SSO for identity, keep roles/permissions in your own database (or derive them from group claims via a mapping table). Don't read authorization decisions directly from the IdP response on every request — you'll couple your request lifecycle to IdP latency and availability.

Handle the logout story explicitly. Local logout (Auth::logout(), session invalidate, regenerate token) is not the same as IdP single logout, and most SSO bugs live here. Decide whether "logout" should also redirect to the IdP's end-session endpoint. Test what happens when a user logs out locally and then hits the SSO-protected route again — they'll silently re-authenticate unless you handle it.

Support both web and API surfaces if you have them. Browser flows rely on the session; token/stateless consumers (SPA, mobile, service-to-service) generally need a different path. Don't try to force the web callback flow behind a api middleware group — session and CSRF semantics won't line up.

Test without a live IdP. Stub the HTTP layer (Laravel's Http::fake()) so your test suite exercises the callback path deterministically. Have at least one test asserting that a tampered/replayed state parameter is rejected. Also pin down what Auth::user() returns before and after the callback — that contract is what the rest of your app depends on.

Local development. Point .env at a test IdP tenant with a localhost redirect URI. If the IdP requires HTTPS redirect URIs, use a tunnel rather than disabling verification. Never commit real client secrets — they belong in env/secret manager, and the config file should only ever read from env().

Gotchas and Tips

v4 is a security release — treat the upgrade as mandatory-ish. The version bump exists to raise floors on guzzlehttp/guzzle (^7.15.2) and to add conflict rules blocking vulnerable releases of guzzlehttp/psr7, symfony/http-foundation, symfony/mime, symfony/http-kernel, symfony/polyfill-intl-idn, phpseclib/phpseclib, nesbot/carbon, firebase/php-jwt, and paragonie/random_compat. If your composer update fails after upgrading, that's the point — your lockfile is holding a CVE. Read the conflict message and bump the offending package rather than loosening the constraint.

composer update may fail loudly and confusingly. Because v4 ships conflict rules, the error you see will often name a transitive package you never required directly. Run composer why <package> and composer audit to trace it back. If you're stuck, composer update --with-all-dependencies is usually what resolves the graph.

No code changes required — but verify anyway. The release notes say application code doesn't change. That's true for the package's API surface, not for your app's own dependency graph. After upgrading, run your test suite and specifically re-test the callback + logout flows; those are the paths most likely to break via an indirect Symfony/Guzzle behaviour change.

Don't be on the wrong side of the PHP/Laravel floor. Dropped PHP < 8.2 and Laravel 8/9 are hard breaks (composer will refuse), but the subtler issue is a CI matrix still running PHP 8.1. Update your pipeline and any Docker base images before merging the bump, or you'll get a red build that looks like a package problem.

Watch the symfony/http-foundation conflict specifically. CVE-2025-64500 and CVE-2024-50345 are called out by name. If you're on a long-lived LTS branch of Laravel 10, make sure your Symfony minor is patched — Laravel's own constraints may allow a range that includes a blocked version.

Cache and config are the classic first-hour bug. After publishing or editing config/sso.php, run php artisan config:clear locally (config:cache in production). A cached stale config produces authentically baffling redirect loops that look like IdP misconfiguration.

Redirect URI must match exactly. Scheme, host, port, trailing slash, and www vs. apex all matter. This is the single most common source of redirect_uri_mismatch errors. Compare the string in config/sso.php to the IdP registration character by character, per environment.

Session and cookie domain in multi-domain apps. If your SSO callback lands on a different subdomain than your app, session cookies won't be shared without explicit SESSION_DOMAIN configuration. Symptom: login appears to succeed, then you're immediately bounced back to the IdP. Fix it in config/session.php, not in the SSO package.

Callback route and CSRF. The IdP POSTs back to you without your CSRF token. If you ever need to move the callback off a route the package manages, you'll have to exclude it from VerifyCsrfToken — and be aware that's a deliberate trade-off, not a free pass.

Debug by logging the claim payload, not by guessing. When a user gets the wrong role or a null attribute, log the decoded claims (behind a debug flag, and never log tokens) and diff them against your mapping. Attribute-name casing and nested-vs-flat claim structure are the usual culprits — IdPs change these between tenants and between protocol versions.

Extension points worth knowing. Before you patch or fork, check the package's service provider for bindable contracts/interfaces (user resolver, claim mapper, HTTP client) and any dispatched events around login. Binding your own implementation in a service provider is upgrade-safe; editing vendor code is not. If the callback behaviour needs to change, look for a published config toggle first — security-focused packages tend to gate the aggressive defaults (e.g. strict claim validation, state enforcement) behind config, and turning those off should require a written justification.

Set a reminder to re-run composer audit. The release notes assert a clean audit at both lowest and highest resolvable dependencies — true at publish time. Since the whole point of v4 is CVE hygiene, make composer audit a CI step so you find out when it stops being true, rather than at the next release.