Looking to hire Laravel developers? Try LaraJobs

laravel-sso-client maintained by tohawk89

Description
Plug-and-play Single Sign-On client for Laravel apps: OAuth 2.0 + PKCE login, user sync and global logout against your SSO server.
Author
Nazar
Last update
2026/11/21 13:16 (dev-main)
License
Downloads
24

Comments
comments powered by Disqus

Laravel SSO Client

Tests

Plug-and-play Single Sign-On for Laravel 12/13 apps. You install it, add three values to .env, and your app signs users in through your central SSO server:

  • /login is sent to the SSO server (OAuth 2.0 authorization code + PKCE).
  • The callback route, user sync and local session are handled for you.
  • Global logout: signing out in any app signs the user out of every app.
  • It works for online and local apps at the same time (back-channel push or polling).
  • Your existing Breeze / Fortify / Livewire starter-kit login is replaced only while SSO is switched on.

Status: early release (0.x). It is tested on PHP 8.3 to 8.5 and Laravel 12 and 13, but the API may still change before 1.0. See CHANGELOG.md.

Requirements

  • PHP 8.3+, Laravel 12 or 13
  • A users table with an email column (the default)
  • An SSO server built on the companion sso-server app

Install

composer require tohawk89/laravel-sso-client
php artisan sso:install

sso:install:

  1. publishes config/sso.php
  2. adds and runs a migration for a nullable unique users.sso_id column
  3. adds the SSO_* keys to .env and .env.example
  4. adds the optional HasSso trait to App\Models\User
  5. prints the callback URL and back-channel logout URL to register on the SSO server

Configure

In the SSO admin, go to Sites → your site → Add environment. Use one environment per place the app runs (Production, Staging, Local). Each environment gets its own client ID and secret. Paste the block it shows into .env:

SSO_ENABLED=true
SSO_URL=https://sso.example.com
SSO_CLIENT_ID=9f1c...
SSO_CLIENT_SECRET=...
SSO_LOGOUT_MODE=auto

Check the setup with:

php artisan sso:test

Safe to install before it's configured

Until SSO_ENABLED=true and SSO_URL, SSO_CLIENT_ID and SSO_CLIENT_SECRET are all set, the package registers no routes and no middleware. Your normal Laravel login keeps working unchanged. If it's enabled but a value is missing, a warning is logged and the app keeps the normal login.

Options

Env Default What it does
SSO_ALLOW_LOCAL_LOGIN false false: /login goes to SSO, and register, password-reset and local 2FA routes redirect to SSO. true: your own login page stays; add <x-sso::login-button /> to it.
SSO_AUTO_CREATE_USERS true Create a local user the first time someone signs in.
SSO_LINK_BY_EMAIL true Link an existing local user with the same email.
SSO_REDIRECT_AFTER_LOGIN /dashboard Where users land after signing in (or the page they originally asked for).
SSO_REDIRECT_AFTER_LOGOUT / Where users land after signing out.
SSO_LOGOUT_MODE auto auto = accept back-channel pushes and poll as a safety net. backchannel = pushes only. poll = polling only (for local machines the server can't reach).
SSO_SESSION_CHECK_INTERVAL 60 Seconds between session checks in auto and poll modes.
SSO_FAIL_OPEN true Keep users signed in if the SSO server is briefly unreachable.
SSO_REDIRECT_URI (APP host)/sso/callback Full callback URL override, for apps behind a proxy.
SSO_REMEMBER false Use Laravel's "remember me" cookie for SSO sign-ins.

Attribute mapping (sync_attributes), the user model and blocked route names are in config/sso.php.

Routes added (only while SSO is active)

Method URI Name
GET /sso/login sso.login
GET /sso/callback sso.callback
GET, POST /login login (SSO-only mode)
POST /logout logout
POST /sso/backchannel-logout sso.backchannel (no CSRF; verified with an RS256 JWT)

The package registers its routes after your app's own routes, so the existing login and logout routes are replaced.

How logout works

  • The user signs out in this app. Any Auth::logout() (the package's /logout, a starter-kit Livewire action or your own code) tells the SSO server through POST /api/logout. The server revokes every token for that user. The package's /logout also clears the SSO browser session.
  • The user signs out somewhere else.
    • Back-channel: the server POSTs a signed logout token to /sso/backchannel-logout. The package verifies it against the server's JWKS and signs the user out on their next request. This works with any session driver.
    • Poll: every SSO_SESSION_CHECK_INTERVAL seconds the middleware calls GET /api/session/check. A revoked token (401) signs the user out here.

Local machines (http://app.test) can't receive pushes from an online server, so use SSO_LOGOUT_MODE=poll there. The SSO admin picks this automatically for local URLs.

Hooks

use Tohawk89\SsoClient\Events\SsoUserSynced;
use Tohawk89\SsoClient\Events\SsoUserLoggedOut;

Event::listen(function (SsoUserSynced $e) {
    // $e->user, $e->ssoUser->getRaw(), $e->wasCreated
    if ($e->wasCreated) {
        $e->user->assignRole('staff');
    }
});

Testing

composer test

License

MIT