README

A reusable Laravel package that connects client applications to a Laravel Passport-based SSO Identity Provider (like sso-server). Handles OAuth2 authentication, webhook-driven user sync, role/permission middleware, and automatic user provisioning.

Features

• 🔐 Custom Socialite Provider — OAuth2 Authorization Code + PKCE with SsoServerProvider
• 🔄 Webhook Receiver — HMAC-signed webhook handler for user sync from SSO server
• 🛡️ Middleware — CheckSsoActive (role access enforcement), VerifySsoSignature (webhook HMAC)
• 👤 User Provisioning — Automatic user create/update from SSO data
• 🧩 Fully Configurable — Override User model, jobs, controllers, middleware, and commands via config

Requirements

• PHP 8.3+
• Laravel 11.x, 12.x, or 13.x
• laravel/socialite ^5.28
• MySQL (or any database supported by Laravel)

Installation

composer require tuahweb/php-sso-client-connect

Publish Configuration

php artisan vendor:publish --tag=sso-client-config

Configuration

1. Environment Variables (.env)

Setel SSO_PROVIDER sebagai base URL SSO server. Semua endpoint OAuth2 akan diturunkan secara otomatis.

APP_URL=https://your-app.test
SSO_PROVIDER=https://sso-server.test
SSO_CLIENT_ID=your-oauth-client-id
SSO_CLIENT_SECRET=your-oauth-client-secret
SSO_WEBHOOK_SECRET=your-webhook-secret

Gunakan variabel berikut jika ingin override endpoint individual (opsional):

SSO_REDIRECT_URI=https://your-app.test/auth/sso/callback
SSO_AUTHORIZE_URL=https://sso-server.test/oauth/authorize
SSO_TOKEN_URL=https://sso-server.test/oauth/token
SSO_USER_INFO_URL=https://sso-server.test/api/user
SSO_DASHBOARD_URL=https://sso-server.test/dashboard

2. Service Configuration (config/services.php)

redirect, authorize_url, token_url, user_info_url, dan server_url diturunkan dari SSO_PROVIDER secara otomatis — cukup setel di .env.

Contoh minimal:

'sso' => [
    'client_id' => env('SSO_CLIENT_ID'),
    'client_secret' => env('SSO_CLIENT_SECRET'),
    'redirect' => env('SSO_REDIRECT_URI', env('APP_URL').'/auth/sso/callback'),
    'webhook_secret' => env('SSO_WEBHOOK_SECRET'),
    'server_url' => env('SSO_PROVIDER'),

    // Endpoint berikut diturunkan dari SSO_PROVIDER.
    // Override via env jika path default tidak sesuai.
    'authorize_url' => env('SSO_AUTHORIZE_URL', rtrim(env('SSO_PROVIDER', 'http://sso-server.test'), '/').'/oauth/authorize'),
    'token_url' => env('SSO_TOKEN_URL', rtrim(env('SSO_PROVIDER', 'http://sso-server.test'), '/').'/oauth/token'),
    'user_info_url' => env('SSO_USER_INFO_URL', rtrim(env('SSO_PROVIDER', 'http://sso-server.test'), '/').'/api/user'),
],

3. User Model

Your User model (or any class specified in config('sso.user_model')) should have these columns/methods:

Migration columns:

• uuid('id')->primary() — UUID from SSO server as primary key
• string('name')
• string('email')->unique()
• boolean('is_active')->default(true)
• json('roles')->nullable()
• json('permissions')->nullable()
• timestamp('sso_synced_at')->nullable()

Methods expected by the package (optional, for Gate-based auth):

• hasRole(string $role): bool
• hasPermission(string $permission): bool

4. Middleware Registration (bootstrap/app.php for Laravel 11+)

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'verify.sso.signature' => \Tuahweb\SsoClient\Middleware\VerifySsoSignature::class,
        'check.sso.active' => \Tuahweb\SsoClient\Middleware\CheckSsoActive::class,
    ]);
})

5. Optional: Gate Registration

In App\Providers\AuthServiceProvider:

Gate::before(function ($user, $ability) {
    if (method_exists($user, 'hasPermission')) {
        return $user->hasPermission($ability) ?: null;
    }
    return null;
});

Usage

Routes (Auto-Registered)

The package automatically registers these routes:

You can disable auto-routing in config/sso.php:

'routes' => [
    'auth' => false,    // Disable SSO auth routes
    'webhook' => false, // Disable webhook route
],

Console Commands

# Trigger full sync from SSO server
php artisan sso:full-sync

Logout Behavior

When a user logs out from a client application:

1. Local session only — The client app clears its local session (Auth::logout())
2. SSO session preserved — The user remains authenticated on the SSO server
3. Redirect to SSO dashboard — User is redirected to the SSO server dashboard after logout
4. Access other apps — User can immediately access other client apps without re-authenticating

Example flow:

• User is logged into Client A and Client B
• User clicks logout in Client A
• Client A session is destroyed
• User is redirected to SSO server dashboard
• User can still access Client B without logging in again

Configuration:

# .env
SSO_DASHBOARD_URL=https://sso-server.test/dashboard

// config/sso.php
'routes' => [
    'dashboard_url' => env('SSO_DASHBOARD_URL', 'http://sso-server.test/dashboard'),
],

To implement full SSO logout (log out from SSO server and all clients), you would need to implement a separate logout endpoint on the SSO server that revokes tokens and triggers logout webhooks to all clients.

Customization

Override the User Model

// config/sso.php
'user_model' => App\Models\YourCustomUser::class,

Override the Webhook Job

Create your own job class that extends the default:

namespace App\Jobs;

use Tuahweb\SsoClient\Jobs\ProcessSsoWebhookJob;

class CustomProcessSsoWebhookJob extends ProcessSsoWebhookJob
{
    public function handle(): void
    {
        // Custom logic before/after sync
        \Log::info('Processing webhook', ['event' => $this->event]);

        parent::handle();
    }
}

Then update config:

// config/sso.php
'jobs' => [
    'process_webhook' => \App\Jobs\CustomProcessSsoWebhookJob::class,
],

Override Controllers

Extend any package controller and override methods:

namespace App\Http\Controllers\Auth;

use Tuahweb\SsoClient\Http\Controllers\SsoController as BaseSsoController;

class SsoController extends BaseSsoController
{
    protected function authenticatedRedirect($user): RedirectResponse
    {
        return redirect()->intended('/custom-dashboard');
    }

    protected function loginFailedRedirect(string $message): RedirectResponse
    {
        return redirect()->route('custom.login')
            ->with('error', $message);
    }
}

Then update config:

// config/sso.php
'controllers' => [
    'sso' => \App\Http\Controllers\Auth\SsoController::class,
],

Development

For local development, add a path repository in your consuming project's composer.json:

"repositories": [
    {
        "type": "path",
        "url": "../packages/tuahweb/php-sso-client-connect"
    }
],
"require": {
    "tuahweb/php-sso-client-connect": "*"
}