Sso Laravel Package

Getting Started

Before you install anything, read the repo. This package is a single-author SSO client with zero stars, zero dependents, and a last release of 2021-04-08. Treat it as a reference implementation you may end up owning rather than a dependency you consume blindly. Budget an hour to read composer.json, the service provider, the config file, and the routes file before wiring it into an app.

1. Check the constraint block first. Open composer.json in the package and look at require (laravel/framework or illuminate/support) and autoload.psr-4. A 2021 package will typically cap at Laravel 8. On Laravel 10/11 you'll get a resolution error; decide up front whether you're forking the constraint or vendoring the source into app/ — do not reach for --ignore-platform-reqs and hope.

2. Install and discover.

   composer require megaads/sso
   php artisan vendor:publish --provider="Megaads\Sso\SsoServiceProvider"
   

   If the provider name differs, php artisan about or composer show megaads/sso will reveal the actual namespace. If there's no publishable config, the package is likely reading config('services.sso.*') or a hardcoded env() — check for that before you go hunting for a config file that doesn't exist.

3. Where to look first, in order: the service provider (what's bound into the container, what middleware alias is registered, whether routes are auto-loaded), the config file (server URL, client id/secret, callback path, scopes/attributes), the routes file (the callback route name and whether it's under web or api), then README.md. The provider tells you more than the README will.

4. First use case — a single protected route group. Set the SSO server URL and client credentials in .env, register the callback URL in the SSO server's client registry, then wrap one route group in the package middleware:

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

   Verify the full round trip — redirect out, authenticate on the SSO server, land back on the callback, arrive at /dashboard with Auth::user() populated — on staging before touching production routes. This is a one-afternoon integration if the package is healthy; if it isn't, you want to find that out on one route, not twenty.

Implementation Patterns

Middleware on groups, not on individual routes. The whole value of an SSO client is that it's declarative at the routing layer. Keep sso on a route group and make sure the callback route sits outside that group — a callback protected by the middleware that triggers the redirect is an infinite loop, and it's the single most common misconfiguration with these packages.

Decide your user-mapping policy explicitly. There are three viable models:

• Pre-provisioned: the user must already exist locally; the callback looks them up by the SSO subject/email and logs them in. Safest, most ops overhead.
• Just-in-time provisioning: create a local User on first callback, populate name/email from the SSO payload. Convenient, but you now own a sync problem when attributes change upstream.
• Stateless: keep the SSO identity in the session and never touch the users table.

Pick one and write it into your own callback handling or a small listener, rather than letting the package's default behavior silently decide for you. If the package ships its own callback controller, check whether it's overridable (a config-driven controller class or a bindable contract) before you fork it.

Wrap it in your own guard/adapter. Bind the package behind a thin interface of your own (SsoAuthenticator::redirect(), ::user(), ::logout()) and resolve it from the container. When the package is abandoned — and at 0 stars/2021, assume it will be — you swap one binding instead of grepping for Megaads\Sso across the codebase.

Configure per environment. The callback URL must be exact and environment-specific (https://app.test/auth/sso/callback vs. production). Drive it from APP_URL in config, not a hardcoded literal, and cache-clear after changing it. If the package reads env() directly inside src/, move that into a config file — env() calls return null once config:cache runs, which produces a spectacularly confusing production-only failure.

Logout is two problems. Clear the local session (Auth::logout(), session()->invalidate(), regenerate the CSRF token) and decide whether to hit the SSO server's logout endpoint so the central session dies too. Local-only logout means the user is silently signed back in on the next request. Check whether the package exposes a remote logout URL; if not, add one.

Test with a fake. Point the SSO server URL at a local stub route (or Http::fake() if the package uses the HTTP client) in your test suite, and assert the redirect URL contains the expected client id and callback. An SSO integration you can't test without a live identity provider will rot within a quarter.

Gotchas and Tips

The maintenance risk is the headline. Zero stars, zero dependents, no release since April 2021. That means: no Laravel 10/11 support, no security patches, no PHP 8.2+ compatibility guarantees. If you adopt it, pin the exact version in composer.json, commit the resolved lock entry, and plan to fork it into your own VCS namespace (repositories with a vcs type) so you control the constraint block. Never composer update your way into a surprise.

Callback URL and cookie domain are where this breaks. Behind a load balancer, TrustProxies must be configured or Laravel generates http:// callback URLs and the SSO server rejects the mismatch. Set SESSION_DOMAIN correctly and SESSION_SECURE_COOKIE=true in production. The callback path registered on the SSO server and the one in your config must match character for character, including trailing slash.

CSRF on the callback. If the callback route is POST and lives in the web group, you'll get a 419 unless the package's provider excludes it from VerifyCsrfToken or it's a GET. Check app/Http/Middleware/VerifyCsrfToken.php — and if you have to add an exception, add the narrowest possible path.

Debugging checklist, in order: dump the outgoing redirect URL (client id, scope, state, redirect_uri), check the SSO server's client registry for the exact redirect URI, log the raw callback payload before your mapping logic, then confirm Auth::login() actually received a user with a valid primary key. Nine times out of ten the failure is redirect URI mismatch or a missing session cookie, not the package's logic.

Verify the state parameter is actually validated. Older SSO clients often skip it. If the package doesn't compare the returned state against the session value, you have a CSRF hole in the login flow and you should add the check yourself in the callback.

Extension points to look for: container bindings in the provider (rebind to your own implementation), publishable views for any login page, and whether routes are registered conditionally (if (! $this->app->routesAreCached()) or a config('sso.routes') flag) — if they're not, you can't override the callback route and you'll be fighting the package rather than using it.

Run a security read-through before production. It's a few hundred lines at most. Specifically check: is the client secret read from config or hardcoded, is the callback payload trusted without signature verification, and is the session regenerated on login (session()->regenerate() to prevent fixation). Any of those missing turns this into a "vendor it and fix it" job rather than an install.