laravel-sso-client maintained by tohawk89
Laravel SSO Client
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:
/loginis 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
emailcolumn (the default) - An SSO server built on the companion
sso-serverapp
Install
composer require tohawk89/laravel-sso-client
php artisan sso:install
sso:install:
- publishes
config/sso.php - adds and runs a migration for a nullable unique
users.sso_idcolumn - adds the
SSO_*keys to.envand.env.example - adds the optional
HasSsotrait toApp\Models\User - 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 throughPOST /api/logout. The server revokes every token for that user. The package's/logoutalso 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_INTERVALseconds the middleware callsGET /api/session/check. A revoked token (401) signs the user out here.
- Back-channel: the server POSTs a signed logout token to
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