cleaniquecoders/laravel-config-sso

Database-backed SSO provider configuration for Laravel with a Livewire + Flux admin UI.

1.0.1 2026-06-08 14:08 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^12.0||^13.0
• illuminate/database: ^12.0||^13.0
• illuminate/support: ^12.0||^13.0
• laravel/socialite: ^5.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.14
• livewire/flux: ^2.0
• livewire/livewire: ^3.5||^4.0
• mockery/mockery: ^1.6
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^10.0||^11.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• socialiteproviders/keycloak: ^5.0
• socialiteproviders/microsoft-azure: ^4.0||^5.0
• spatie/laravel-ray: ^1.35

Suggests

• livewire/flux: Flux UI components used by the optional admin screen.
• livewire/livewire: Required for the SSO providers admin screen (UI).
• socialiteproviders/keycloak: Adds the Keycloak (OIDC) Socialite driver.
• socialiteproviders/microsoft-azure: Adds the Azure AD Socialite driver.
• spatie/laravel-permission: Enables automatic role assignment for users created on first SSO login.

MIT

• Nasrul Hazim Bin Mohamad

• laravel
• Cleanique Coders
• laravel-config-sso

README

Manage single sign-on (SSO) identity providers from your database — no .env juggling, no redeploys. Providers (Google, GitHub, GitLab, Bitbucket, Keycloak, Azure AD) are stored with an encrypted client secret and per-driver config, exposed through a Laravel Socialite redirect/callback flow that finds-or-creates and links the local user — plus an optional Livewire + Flux admin screen to manage them.

• 🔐 DB-backed providers, encrypted client_secret and OAuth token_data
• 🧩 Core drivers via laravel/socialite; Keycloak / Azure via optional socialiteproviders/*
• 🖥️ Optional Livewire 4 + Flux admin UI (create / edit / enable / delete)
• 🧱 App-agnostic — configurable user model, table names, and authorization gate
• ✅ Laravel 12 & 13, PHP 8.2+

Quickstart

composer require cleaniquecoders/laravel-config-sso

# Publishes the config, publishes + runs the migrations, all in one step
php artisan config-sso:install

Then:

1. Point the package at your user model and the gate that guards the admin UI in config/config-sso.php:

   'user_model' => App\Models\User::class,
   'gate'       => 'admin.manage.sso',   // or null to disable the check

2. Drop the login buttons into your login view — no extra markup required:

   <x-sso />

3. (Optional) install the admin UI and extra drivers:

   composer require livewire/livewire livewire/flux                 # admin UI
   composer require socialiteproviders/keycloak socialiteproviders/microsoft-azure   # Keycloak / Azure AD

That's it — add a provider in the admin screen (or seed SsoProvider directly) and it appears on your login page.

Installation (manual)

If you prefer not to use the installer:

php artisan vendor:publish --tag="laravel-config-sso-migrations" && php artisan migrate
php artisan vendor:publish --tag="laravel-config-sso-config"
php artisan vendor:publish --tag="laravel-config-sso-views"   # optional — customize the UI

Configuration

Set the host application's user model and the gate that protects the admin UI:

// config/config-sso.php
'user_model' => App\Models\User::class,
'gate'       => 'admin.manage.sso',   // or null to disable the check

Everything else (drivers, table names, redirect routes, registration behaviour, route prefixes/middleware) is documented inline in the published config file.

Usage

Render login buttons

The bundled <x-sso /> Blade component renders provider buttons (Tailwind-styled, dark-mode ready, no Flux dependency so it's safe on a public login page):

<x-sso />                              {{-- all active providers --}}
<x-sso provider="github" />           {{-- a single provider --}}
<x-sso only="github,keycloak" />      {{-- a subset, in the given order --}}
<x-sso class="mt-4" />                 {{-- merge your own classes --}}

The tag is configurable via config-sso.component (default sso) — set it to another name to avoid clashes, or null to not register a global tag.

Or build the markup yourself with the facade:

@foreach (\CleaniqueCoders\ConfigSso\Facades\ConfigSso::providers() as $provider)
    <a href="{{ route('sso.redirect', $provider->driver) }}">Continue with {{ $provider->name }}</a>
@endforeach

sso.redirect and sso.callback are registered automatically. On callback the package finds a user by email (creating one when registration.enabled is true), links the identity, stores the tokens, logs the user in, and redirects to the redirect.home route.

Admin UI

When Livewire is installed, a full-page management screen is registered at config-sso.admin.prefix (default admin/settings/sso). Or embed it anywhere:

<livewire:config-sso.admin />

The ConfigSso facade

ConfigSso::enabled();              // bool — master feature toggle
ConfigSso::providers();            // Collection<SsoProvider> — active, ordered
ConfigSso::drivers();              // ['google' => 'Google', ...]
ConfigSso::driverFields('keycloak'); // ['base_url', 'realms']

Testing

composer test

The suite (Pest + Orchestra Testbench) covers the models, the redirect/callback flow (Socialite mocked), the ConfigSso facade, the Livewire admin component, the <x-sso /> component, and a full end-to-end sign-in journey (tests/Feature/EndToEndTest.php).

Local development (try it in a real app)

A Testbench workbench app lives in workbench/ so you can click through the package in a browser without wiring it into a host project:

composer install
composer serve

composer serve builds a SQLite database, runs the migrations, seeds demo data, and boots the app at http://127.0.0.1:8000. Then:

• / — the login page rendering <x-sso />
• /dev/login — log in as the seeded admin ([e-mail] / password)
• /admin/settings/sso — the Livewire + Flux admin UI

Seeded providers use placeholder credentials, so clicking a button reaches the real IdP and fails at their end — edit a provider with real client_id / client_secret to complete a full OAuth round trip. Run composer build any time to reset the demo database.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Nasrul Hazim Bin Mohamad
• All Contributors

License

The MIT License (MIT). Please see License File for more information.