Laravel SSO

Sign staff in to a Laravel app through an OpenID Connect SSO portal. The portal handles sign-in, two-step verification and who may open the app. The app keeps its own users and roles.

You need the app registered in the portal, with its client ID and secret.

Installation

composer require webimpian/laravel-sso
php artisan migrate

The migration adds sso_sub and sso_pending to the users table.

Copy the .env block from the app's Connection tab in the portal:

SSO_ISSUER=https://sso.example.com
SSO_CLIENT_ID=your-client-id
SSO_CLIENT_SECRET=your-client-secret

Send guests to the portal, and sign out through it:

// routes/web.php
Route::redirect('login', 'auth/sso/login')->name('login');

<form method="POST" action="{{ route('sso.logout') }}">
    @csrf
    <button>Sign out</button>
</form>

Then add these URLs to the app in the portal:

The portal calls the back-channel URL server to server, so let it through Cloudflare.

How it works

The idle timeout and check interval are set per app in the portal. Sessions that didn't come from the portal, such as a break-glass admin login, are left alone.

Accounts

SSO_PROVISIONING decides what a first sign-in without an account gets:

To change how accounts are found or created, set callbacks in AppServiceProvider::boot():

use Webimpian\Sso\Accounts;
use Webimpian\Sso\Sso;
use Webimpian\Sso\SsoException;

Sso::createUsersUsing(fn (array $claims) => (new User)->forceFill([
    'name' => $claims['name'],
    'email' => $claims['email'],
    'user_type' => UserType::Staff,
]));

Sso::resolveUsersUsing(function (array $claims) {
    $user = Accounts::resolve($claims);

    if ($user->suspended_at !== null) {
        throw SsoException::refuse('Your access to this app was removed.');
    }

    return $user;
});

The claims are sub, sid, name, email and picture, plus roles and workos_user_id with the staff scope.

Roles

Roles stay in the app. To copy the portal's WorkOS roles on every sign-in, map them:

SSO_ROLE_MAP=admin:admin,member:viewer
SSO_DEFAULT_ROLE=viewer

Models with syncRoles() (Spatie Permission) work as they are. Otherwise, tell the package how to give roles:

Sso::syncRolesUsing(fn (User $user, array $roles) => $user->update(['role' => $roles[0] ?? 'viewer']));

A role map or SSO_WORKOS_ID_COLUMN adds the staff scope, which an admin must allow on the app's Access tab.

Adding and removing staff

An app can manage its own staff once an admin turns on Can manage staff on its Access tab.

$staff = Sso::addStaff('aina@example.com', 'Aina', 'Rahman');
User::create(['name' => $staff['name'], 'email' => $staff['email'], 'sso_sub' => $staff['sub']]);

Sso::removeStaff($user->sso_sub);

• addStaff() creates new people in WorkOS and the portal, and finds people already on staff. Nobody is emailed, so tell them to sign in.
• For an app with an access list, addStaff() adds them to it, and removeStaff() takes them off and signs them out of the app at once.
• For an app open to all staff, or by role or group, that access stays with portal admins, and access_reason says so.
• People outside the company open only the apps whose list names them. addStaff() can't create them, but both calls add or remove an existing one on this app's list, whatever its access mode.
• Refusals throw SsoException with the portal's reason and status: 409 revoked, 422 not a company address, 503 WorkOS down.

Revoked staff

When a portal admin revokes someone, the portal deactivates their WorkOS membership, signs them out of every app, and tells each app they used or are listed on. The package ends their sessions and fires an event, so the app can suspend the account itself:

use Webimpian\Sso\Events\StaffRestored;
use Webimpian\Sso\Events\StaffRevoked;

Event::listen(StaffRevoked::class, fn (StaffRevoked $event) => $event->user->update(['suspended_at' => now()]));
Event::listen(StaffRestored::class, fn (StaffRestored $event) => $event->user->update(['suspended_at' => null]));

The notice comes through the back-channel logout URL. Without a listener, the account stays as it is and the person can't sign in.

Filament

Panels don't use the web group, so add the middleware to each panel:

use Webimpian\Sso\Http\Middleware\KeepSsoSession;

return $panel
    ->login(null)
    ->middleware([
        // ...the panel's other middleware
        KeepSsoSession::class,
    ]);

Guests go to the portal through the login route, and the user menu signs out through it on Filament 3, 4 and 5.

Moving off an app's own WorkOS login

Testing

Sso::fake() signs people in, and answers addStaff() and removeStaff(), without calling the portal:

Sso::fake(['email' => $user->email, 'roles' => ['admin']]);

$this->followingRedirects()->get('/dashboard')->assertOk();

Configuration

php artisan vendor:publish --tag=sso-config publishes the config, and --tag=sso-views the package's two pages.

License

MIT. See LICENSE.md.