Laravel Sso Client Laravel Package

Getting Started

Install the client alongside laravel-sso-server 1.1 (this package targets the same release line):

composer require laravel-sso-client
php artisan vendor:publish --tag=sso-client-config

First places to look after publishing config/sso-client.php:

1. endpoints — verify it now contains the logout entry. If you published the config before 1.1.0, add it manually:

   'endpoints' => [
       'authorize' => '/sso/authorize',
       'token'     => '/sso/token',
       'userinfo'  => '/sso/userinfo',
       'logout'    => '/sso/logout', // new in 1.1.0
   ],
   

2. post_logout_redirect_uri — set this to a route name (defaults to home). It must be same-origin with the OAuth redirect URI or the server will reject the logout handshake.
3. link_existing_users_by_email — decide now, because it interacts with the new email_verified enforcement.

First end-to-end use case: wire up the standard authorize → token → userinfo login flow, then add a logout button that POSTs to route('sso-client.logout'). That single route now covers both local session teardown and federated logout against the server.

<form method="POST" action="{{ route('sso-client.logout') }}">
    @csrf
    <button type="submit">Log out</button>
</form>

Implementation Patterns

Login (unchanged from 1.0): Redirect users to the authorize endpoint, handle the callback, resolve the local User via userinfo. The new email_verified claim slots into this step — the package only links to an existing account by email when the server returns email_verified: true. Servers that omit the claim preserve 1.0 behavior (link succeeds), so mixed-version deployments keep working.

Federated logout workflow:

• The sso-client.logout route is CSRF-protected and POST-only. It ends the local session, looks up the stored access token, and 302s to the server's /sso/logout with token_hint=<access_token>.
• The server terminates the SSO session, notifies the user's other apps, and redirects back to post_logout_redirect_uri.
• This means one logout button logs the user out everywhere — treat that as an architectural decision, not a UI detail. Document it for product.

Upgrade pattern (0.x→1.1): Users who signed in before the upgrade have no stored access token. After upgrade, clicking logout will only clear the local session; the server side stays authenticated. Plan a re-auth nudge or accept that legacy sessions won't get federated logout. There is no way to retroactively mint a token.

Boost integration: The package ships a guideline and an sso-client-development skill in resources/boost. If you use Laravel Boost, wire the guideline into your project so future AI assistants don't generate GET logout links (a classic mistake) or forget the logout endpoint entry.

Testing pattern: The release was validated against SQLite, MySQL, and PostgreSQL on PHP 8.4 / Laravel 13 with interop tests against laravel-sso-server 1.1.0. Mirror that in your test suite with a fake SSO server and assert both the token exchange and the logout POST body containing token_hint.

Gotchas and Tips

• GET logout silently breaks federation. If any view, email link, or legacy route still uses <a href="/sso/logout">, the user is logged out locally but the SSO session persists. Audit all logout surfaces; convert to POST.
• post_logout_redirect_uri origin matters. The server enforces same-origin with the registered OAuth redirect URI. A subdomain mismatch (e.g. app.example.com vs www.example.com) will reject the post-logout redirect.
• CSRF is real. The logout route is CSRF-protected. Fetch or form POST both need @csrf. API or stateless logout needs a different approach — the package does not provide a token-based logout.
• Upgrading without republishing config: 1.0 configs lack logout in endpoints, so route('sso-client.logout') may resolve but the redirect target won't be found. Add it manually or republish and diff.
• email_verified nuance: with link_existing_users_by_email enabled and the server returning email_verified: false, the login is refused for existing accounts. In legacy email-only mode (no claim sent), unverified existing users are also refused — verify your server sends the claim if you want permissive 1.0 behavior.
• Token storage scope: federated logout sends the access token as token_hint in a query string. That token ends up in the server's access logs and browser history. Review with security: it's a hint, and the server should validate it, but you may want to disable access-log capture on the SSO server's logout route.
• Debugging failed logouts: check (a) endpoints.logout present, (b) server version ≥ 1.1, (c) post_logout_redirect_uri origin matches OAuth redirect, (d) the user's session predates the upgrade if they seem only locally logged out.
• Extension point: the logout controller is a single route; wrap or override via route registration order if you need custom side effects (e.g. clearing tenant cookies) before redirecting to the server.