README

A universal, production-ready SSO client for Laravel (10, 11, 12), Filament, API, and Native PHP applications. Supports both session-based and token-based authentication flows.

📋 Table of Contents

• Features
• Installation
• Configuration
• Usage Examples
  • 1. Laravel Web (Session)
  • 2. Laravel Filament
  • 3. Laravel API (Token)
  • 4. PHP Native
• Customization
• Clean Architecture

🚀 Features

• Multi-Framework: Support for Laravel 10, 11, and 12.
• Filament Ready: Seamless integration with Filament v3+.
• Dual Mode:
  • session: For traditional web apps & Filament (Stateful).
  • token: For APIs & SPAs like React/Vue (Stateless).
• PHP Native: Work outside Laravel using cURL.
• Manager Pattern: Extensible driver system.

📦 Installation

Install the package via composer:

composer require gungcahyadipp/sso-client

Publish the configuration (Laravel):

php artisan sso-client:install

Note: During installation, you will be prompted to publish a customizable SSO Controller. Type yes if you want to modify the callback logic.

⚙️ Configuration

Add these to your .env file:

SSO_MODE=session # Use 'session' for Web/Filament, 'token' for API
SSO_BASE_URL=https://sso.yourserver.com
SSO_CLIENT_ID=your-client-id
SSO_CLIENT_SECRET=your-client-secret
SSO_REDIRECT_URI=http://your-app.com/sso/callback

🛠️ Usage Examples

1. Laravel Web (Stateful / Session)

Ideal for standard Laravel blade applications.

Route Protection: Apply the sso.auth middleware to your routes.

// routes/web.php
Route::middleware(['sso.auth'])->group(function () {
    Route::get('/dashboard', function () {
        return view('dashboard');
    });
});

Automatically Registered Routes: The package provides these routes out of the box:

• route('sso.login') -> /sso/login (Redirects to SSO Server)
• route('sso.callback') -> /sso/callback (Handles authentication)
• route('sso.logout') -> /sso/logout (POST)

Adding the SSO Login Button

You can add a simple link or button in your login page (Blade):

<!-- Simple Link -->
<a href="{{ route('sso.login') }}" class="btn btn-primary">
    Login with SSO
</a>

<!-- Or using a form for better security/styling -->
<form action="{{ route('sso.login') }}" method="GET">
    <button type="submit" class="btn-sso">
        Sign in with Account SSO
    </button>
</form>

Custom Login Logic: The package provides /sso/login and /sso/callback routes out of the box.

2. Laravel Filament (v3/v4/v5)

Since Filament uses Laravel's default guard, it works automatically.

Setup:

1. Set SSO_MODE=session.
2. Apply sso.auth middleware in your Panel Provider:

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        ->authMiddleware([
            \GungCahyadiPP\SSOClient\Http\Middleware\AuthenticateSSO::class,
        ]);
}

3. Laravel API (Stateless / Token)

For separate React/Vue frontends.

Config:

SSO_MODE=token

Workflow: Frontend redirects to SSO server, gets code, then sends it to your API.

// Your API Controller
use GungCahyadiPP\SSOClient\Facades\SSOClient;

public function authenticate(Request $request) {
    $result = SSOClient::handleCallback($request->code);
    
    // Returns structured JSON for frontend:
    // { "status": "success", "access_token": "...", "user": { ... } }
    return response()->json($result);
}

4. PHP Native (Without Laravel)

Use the standalone client in any PHP project.

require 'vendor/autoload.php';

use GungCahyadiPP\SSOClient\Native\SSONativeClient;

$config = [
    'base_url' => 'https://sso.server.com',
    'client_id' => '...',
    'client_secret' => '...',
    'redirect_uri' => '...',
    'endpoints' => [
        'authorize' => '/oauth/authorize',
        'token' => '/oauth/token',
        'user' => '/api/v1/me',
    ]
];

$client = new SSONativeClient($config);

// 1. Get Redirect URL
$url = $client->getRedirectUrl();
header("Location: $url");

// 2. In your callback script:
$token = $client->getToken($_GET['code']);
$user = $client->getUser($token['access_token']);

print_r($user);

🎨 Customization

If you need to customize the login or callback logic (e.g., adding custom role checks or data synchronization), publish the SSO controller:

php artisan vendor:publish --tag=sso-controller

This will create app/Http/Controllers/Auth/SSOController.php.

Logic Branching

The stub controller handles different modes automatically:

• handleSessionCallback(): Logic for Laravel Web/Filament.
  • Call SSOClient::loginUser($user) to authenticate.
• handleTokenCallback(): Logic for API/React.
  • Returns a structured JSON response for your frontend.

Update your config/sso-client.php to use the new controller:

'controller' => \App\Http\Controllers\Auth\SSOController::class,

🏗️ Clean Architecture

This package uses the Manager Pattern. You can extend it by adding your own drivers in the Drivers/ directory and registering them in the SSOManager.

🔒 Security

If you discover any security-related issues, please email gungcahyadipp@gmail.com instead of using the issue tracker.

📄 License

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