PHPackages                             tuahweb/php-sso-client-connect - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. tuahweb/php-sso-client-connect

ActiveLibrary

tuahweb/php-sso-client-connect
==============================

SSO Client Connect — Laravel package for connecting client apps to an OAuth2 SSO server. Socialite provider, webhook receiver, middleware, and user sync.

v1.0.0(1mo ago)03MITPHPPHP ^8.3

Since Jul 15Pushed 1mo agoCompare

[ Source](https://github.com/tuahweb/php-sso-client-connect)[ Packagist](https://packagist.org/packages/tuahweb/php-sso-client-connect)[ RSS](/packages/tuahweb-php-sso-client-connect/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (4)Versions (3)Used By (0)

tuahweb/php-sso-client-connect — SSO Client Connect for Laravel
===============================================================

[](#tuahwebphp-sso-client-connect--sso-client-connect-for-laravel)

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
--------

[](#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
------------

[](#requirements)

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

Installation
------------

[](#installation)

```
composer require tuahweb/php-sso-client-connect
```

### Publish Configuration

[](#publish-configuration)

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

Configuration
-------------

[](#configuration)

### 1. Environment Variables (`.env`)

[](#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`)

[](#2-service-configuration-configservicesphp)

`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

[](#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+)

[](#4-middleware-registration-bootstrapappphp-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

[](#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
-----

[](#usage)

### Routes (Auto-Registered)

[](#routes-auto-registered)

The package automatically registers these routes:

MethodURINameDescriptionGET`/auth/sso/redirect``auth.sso.redirect`Redirect to SSO loginGET`/auth/sso/callback``auth.sso.callback`Handle SSO callbackPOST`/webhook/sso-sync``webhook.sso-sync`Webhook receiverYou can disable auto-routing in `config/sso.php`:

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

### Console Commands

[](#console-commands)

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

### Logout Behavior

[](#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
-------------

[](#customization)

### Override the User Model

[](#override-the-user-model)

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

### Override the Webhook Job

[](#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

[](#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
-----------

[](#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": "*"
}
```

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance90

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

47d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/5f1c5e62d2b201325134cb6950d6dd176f17c9cf8f29101b8ec0eee594e0d4f3?d=identicon)[acakluqman](/maintainers/acakluqman)

---

Top Contributors

[![acakluqman](https://avatars.githubusercontent.com/u/25748055?v=4)](https://github.com/acakluqman "acakluqman (3 commits)")

---

Tags

laravelSSOsocialiteoauth2passport

### Embed Badge

![Health badge](/badges/tuahweb-php-sso-client-connect/health.svg)

```
[![Health](https://phpackages.com/badges/tuahweb-php-sso-client-connect/health.svg)](https://phpackages.com/packages/tuahweb-php-sso-client-connect)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3365.5M359](/packages/psalm-plugin-laravel)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

80732.6M270](/packages/laravel-mcp)[laravel/socialite

Laravel wrapper around OAuth 1 & OAuth 2 libraries.

5.7k118.2M1.0k](/packages/laravel-socialite)[laravel/scout

Laravel Scout provides a driver based solution to searching your Eloquent models.

1.7k59.5M712](/packages/laravel-scout)[illuminate/auth

The Illuminate Auth package.

10528.8M1.4k](/packages/illuminate-auth)[illuminate/routing

The Illuminate Routing package.

1419.6M3.8k](/packages/illuminate-routing)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)