Search by

tohawk89 / laravel-sso-client

tohawk89

Plug-and-play Single Sign-On client for Laravel apps: OAuth 2.0 + PKCE login, user sync and global logout against your SSO server.

Package info

github.com/tohawk89/laravel-sso-client

pkg:composer/tohawk89/laravel-sso-client

Statistics

Installs: 24

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.2.0 2026-11-21 12:16 UTC

This package is auto-updated.

Last update: 2026-11-21 12:16:37 UTC


README

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

Updating

After composer update, run php artisan sso:install again. It only adds what is new: new migrations are published and run, missing .env keys are added, and your config/sso.php is kept (it tells you if the latest version has new options; use --force to replace it, a backup is saved as config/sso.php.bak). Existing data is never touched: the migrations skip changes that are already in the database.

Apps installed with 0.1.0 have an untimestamped add_sso_id_to_users_table.php migration; re-running sso:install renames it to a standard timestamped name and updates the migrations table so it is not run again.

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