Sso Client Laravel Package

Getting Started

This is a small, single-maintainer package (last release August 2021, no stars, no dependents), so treat the source as the documentation. Budget 30–60 minutes to read it before wiring it in.

1. Install and inspect the constraint first.

   composer require megaads/sso-client
   

   Immediately open vendor/megaads/sso-client/composer.json and check the illuminate/* and php constraints. If you are on Laravel 9+ you will likely need --ignore-platform-reqs or a fork with widened constraints.

2. Register the provider. Check src/*ServiceProvider.php for whether it is auto-discovered and whether it registers a facade or a guard driver. Add it to config/app.php manually if discovery fails.

3. Publish and read the config.

   php artisan vendor:publish --provider="Megaads\SsoClient\SsoServiceProvider"
   

   Open config/sso.php and map every key to an env var. The keys you care about are the SSO server base URL, the client/app identifier, the client secret, and the callback/redirect URI.

4. Where to look first, in order:

   • config/sso.php — the contract with the SSO server.
   • src/Http/Middleware/ — how it decides a user is authenticated.
   • src/Http/Controllers/ — the login redirect and callback handler.
   • routes/*.php — which URIs the package registers (login, callback, logout).
   • src/Models/ or a trait — how it materialises a local user.

5. First use case: protect a single dashboard route group, redirect unauthenticated users to the SSO server, and on callback log them into Laravel's session. Do not migrate your whole auth stack on day one — put the middleware on one route group and keep the default web guard working alongside it.

Implementation Patterns

Middleware-guarded route group. The package's value is a middleware that bounces guests to the SSO login endpoint. Apply it to a group rather than globally:

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

Confirm the exact alias in the service provider ($router->aliasMiddleware(...)).

Callback → local user mapping. The callback controller will hand you an identity payload (array or DTO). The day-to-day pattern is to resolve it to an Eloquent user with a stable key, never by email alone:

$user = User::firstOrCreate(
    ['sso_id' => $payload['id']],
    ['name' => $payload['name'], 'email' => $payload['email']]
);
Auth::login($user, true);

Add a sso_id column with a unique index. On every login, sync roles/attributes from the SSO payload so deprovisioning propagates.

Logout that actually logs out. Local Auth::logout() leaves the SSO session alive, so the next request silently re-authenticates. Use the package's logout route (or redirect to the SSO server's logout URL) and invalidate the session + regenerate the CSRF token.

Testing. The callback makes an outbound HTTP call, so stub it:

Http::fake(['sso.example.com/*' => Http::response(['id' => 1, 'email' => '[email protected]'])]);
$this->get('/sso/callback?code=test')->assertRedirect('/dashboard');

Assert both the happy path and a tampered/expired token path.

Integration tips.

• Keep the callback route outside any auth middleware but inside web for session access.
• Exclude the callback from CSRF only if the package's flow requires it (VerifyCsrfToken::$except); prefer keeping it on if state is validated server-side.
• If you already use Laravel Socialite, consider whether this package adds anything Socialite's generic OAuth driver cannot — often it does not.

Gotchas and Tips

• It is effectively unmaintained. Zero stars, zero dependents, last commit 2021. Pin an exact version in composer.json, and plan to fork into packages/ if you need to bump Laravel support.
• Audit the token verification yourself. Read exactly how the callback validates the response — signature, JWT iss/aud/exp, or a plain trusted GET. Anything that trusts an identifier passed in the query string is a critical vulnerability. Do not ship to production on faith.
• Redirect URI must match byte-for-byte. A trailing slash or http vs https mismatch against what is registered on the SSO server is the #1 cause of "invalid_client"/"invalid_redirect_uri" errors. Check the value after php artisan config:cache.
• Config caching bites. Env changes are invisible until php artisan config:clear. During local debugging, run config:clear after every .env edit.
• Cross-domain sessions. If the SSO server is on a sibling domain, cookie domain, SameSite, and Secure settings all matter. Session state mismatches usually mean the state cookie was dropped — set SESSION_DOMAIN deliberately and test in a real browser, not just php artisan serve with curl.
• Laravel version drift. Service providers from the 5.x/6.x/7.x era often use defer, register() signatures, or facade aliases that newer versions tolerate but deprecate. Watch storage/logs/laravel.log for BindingResolutionException on the guard.
• Debugging the flow. Temporarily log the raw callback request and the SSO response body; the package likely swallows failures into a generic redirect. Add a Log::debug() in the callback controller rather than guessing.
• Extension points. Override the controller or middleware by re-binding it in your own service provider or repointing the config key, and publish the package's views if it renders an error page. Prefer subclassing over editing vendor/.
• Escape hatch. If the source is thin, reimplement the flow in ~100 lines with Laravel's HTTP client and a signed state parameter. That is often safer than depending on an unmaintained, unaudited auth package.